ui updates

docs/cookbook/ui.md

@@ -61,22 +61,6 @@ render(setup, {
 });
 ```
 
-## Hiding Spaces
-
-To hide a `Space` make `render` equal `false` on the appearance:
-
-```ts
-$.discard.appearance({ render: false });
-```
-
-## Hide Space For Everyone But Me
-
-Often spaces only need to be visibile to a player if the `Space` is owned by that player. Thus you can hide everything else to reduce clutter. This example shows you how to hide every player's `hand` except for their own.
-
-```ts
-game.all("hand", { mine: false }).appearance({ render: false });
-```
-
 ## Drawers
 
 To turn a normal `Space` into a drawer that opens and closes to save space, you just need to apply a layout to it that looks similar to this:

docs/game/modules.md

@@ -9,7 +9,33 @@ imported directly and bring their own behavior and appearance, which can be
 customized. You can even subclass or just copy and edit these modules to create
 your own specialized components for your game.
 
-The only module is current the D6.
+## Flippable
+
+A Piece with two sides: front and back. When the Piece is hidden, the back is
+shown. When visible, the front is shown. When the visibility changes, the
+included CSS animates a 3d flip. The starter token game uses this for flipping
+the tokens to reveal their color, e.g.:
+
+```ts
+  import { Flippable } from '@boardzilla/core/components';
+
+  ...
+  // in the "ui/index.tsx" layout() method
+   Piece.appearance({
+      render: piece => (
+        <Flippable>
+          <Flippable.Front>{piece.name}</Flippable.Front>
+          <Flippable.Back></Flippable.Back>
+        </Flippable>
+      );
+    });
+
+  // The resultant DOM structure inside the Piece element in this case would be:
+    <div class="bz-flippable">
+      <div class="front">{piece.name}</div>
+      <div class="back"></div>
+    </div>
+```
 
 ## D6
 

docs/ui/appearance.md

@@ -353,52 +353,46 @@ You may notice that by default the playing area starts as a perfect square and
 adjusting the size of the browser window causes the square to change size to be
 as large as it can be and still fit in the viewport. You can customize the
 aspect ratio of the playing area to something other than 1:1 (a square). This is
-done by adding a `boardSizes` function to the main
+done by adding `boardSizes` function to the main
 [`render`](../api/modules#render) function, e.g.:
 
 ```ts
   render({
-    boardSizes: () => ({
-      name: "standard",
-      aspectRatio: 4 / 3
-    })
-    ...
-  })
+    boardSizes: [{
+      name: 'standard',
+      aspectRatio: { min: 8 / 5, max: 2 / 1 },
+    }]
 ```
 
 The board size will always fill as much of the viewport on the player's device
-as it can while maintaining the specified aspect ratio.
+as it staying within the specified aspect ratio range.
 
 ## Responsive and mobile
 
 You can provide multiple aspect ratios and layouts for different screen sizes
 and device types. All of the layout API above can also be targetted to a
-particular screen size or device type. When you supply the `boardSizes` function
-above, you can also accept some parameters to provide different layouts. These
-parameters are:
-
-- `screenX` (the pixel width of the viewport)
-- `screenY` (the pixel width of the viewport)
-- `mobile` (`true` if using a mobile device)
-
-You can then supply different board sizes depending on these values, for example
-having a portrait or landscape version, or simply giving a different version for
-mobile devices, e.g.:
+particular screen size or device type. You can then supply different board sizes
+depending on these values, for example having a portrait or landscape version,
+or simply giving a different version for mobile devices. You can also specify
+how the board fits within the screen if the screen's aspect ratio is outside the
+provided range, e.g.:
 
 ```ts
   render({
-    boardSizes: (screenX, screenY, mobile) => {
-      if (mobile) return {
-        name: "mobile",
-        aspectRatio: 1 / 2
-      });
-      return {
-        name: "standard",
-        aspectRatio: 5 / 3
-      })
-    })
-    ...
-  });
+    boardSizes: [{
+      name: 'mobile',
+      mobile: true, // only use on mobile devices
+      // any aspect ratio within this range is allowed, whatever is closest to the device screen
+      aspectRatio: { max: 16 / 9, min: 22 / 10 },
+      orientation: 'landscape', // lock to landscape orientation
+    }, {
+      name: 'desktop',
+      desktop: true, // only use on desktop
+      aspectRatio: 8 / 5, // use this exact aspect ratio
+      // instead of fitting within the screen size and adding space on either side, instead
+      // stretch the board to fill the screen and use scrollbars as needed
+      scaling: 'scroll'
+    }]
 ```
 
 The name provided is then passed to the main `layout` function in the

docs/ui/css.mdx

@@ -9,6 +9,12 @@ styles are included basic positioning and animation that are not intended to
 change. However all Boardzilla CSS is applied using a CSS `@layer` so that any
 CSS you provide will override these.
 
+:::info box-sizing
+
+All Boardzilla elements use `box-sizing: border-box` by default.
+
+:::
+
 ## DOM element reference
 
 Here you will find a list of all the elements and classes that can be targetted
@@ -145,7 +151,16 @@ the size of the element. This means that any CSS applied to the element can use
 Specific Spaces and Pieces of your board are rendered with this element. They
 always a class name of `Space` or `Piece` depending on the base type. They also
 have a class name matching the Typescript class of the element if it is
-subclassed.
+subclassed, e.g. a `Card` class that extends `Piece` with have CSS class names
+of both `Card` and `Piece`.
+
+This element can be targetted for any styles *except* `transform`. All styles,
+including `transform`, can freely be applied to *your* elements inside the
+Space/Piece that you supply in the
+[`appearance.render`](appearance#render). These elements all appear immediately
+inside this element. Note however, that if you wish to apply `z-index` layering
+for this element relative to other elements next to it, the `z-index` must be
+applied here.
 
 There are additional class names that may be present depending on circumstances,
 and are useful for targetting to customize appearance:
@@ -169,9 +184,6 @@ attributes, e.g.:
   >
 ```
 
-All JSX supplied in the [`appearance.render`](appearance#render) appears
-immediately inside this element.
-
 Also see [appearance](appearance#css).
 
 ### .profile-badge