@typed-grid-areas/solid 0.1.2 → 0.1.3

package/README.md

@@ -20,7 +20,9 @@ you name a grid's regions and write the names down the way the regions sit
 on screen; each child then takes its region by name. The template is a
 picture of the component:
 
-![A template whose area names, icon, title, tag and body, are laid out in the same shape and colours as the card they arrange](https://raw.githubusercontent.com/MichaelBuss/typed-grid-areas/main/docs/images/areas.png)
+[![A template whose area names, icon, title, tag and body, are laid out in the same shape and colours as the card they arrange](https://raw.githubusercontent.com/MichaelBuss/typed-grid-areas/main/docs/images/areas.png)](https://michaelbuss.github.io/typed-grid-areas/#grid-template-areas-in-one-picture)
+
+[Try it live](https://michaelbuss.github.io/typed-grid-areas/#grid-template-areas-in-one-picture): hover an area to find it in both, or untick a slot to watch the picture redraw.
 
 ## Simple on paper, hard in practice
 
@@ -140,10 +142,8 @@ npx @tanstack/intent@latest install
 
 ## Learn more
 
-- [Docs](https://michaelbuss.github.io/typed-grid-areas/): how it works,
-  the concepts, and live examples.
-- [Try it in your browser](https://michaelbuss.github.io/typed-grid-areas/try-it/):
-  a playground, and an example app per framework.
+- [Docs](https://michaelbuss.github.io/typed-grid-areas/): how it works, the concepts, and live examples.
+- [Try it in your browser](https://michaelbuss.github.io/typed-grid-areas/try-it/): a playground, and an example app per framework.
 - [The full API reference](https://github.com/MichaelBuss/typed-grid-areas/blob/main/REFERENCE.md):
   every option and every adapter. It also ships in every package, matching
   the version you installed: `node_modules/typed-grid-areas/REFERENCE.md`.

package/REFERENCE.md

@@ -124,13 +124,18 @@ Compile-time checks, each reported on the offending property:
   `{ _columnCountError: { expected: 2; got: 3 } }` on `columns` (and
   `_rowCountError` on `rows`); skipped for `repeat(` and non-literal strings
 - unknown `align` keys and unknown `when`/`unless` values
+- a breakpoint key that isn't allowed: `{ _unsupportedBreakpoint: "@[50%]" }`
+  on the key, and breakpoints in more than one unit:
+  `{ _mixedBreakpointUnits: "…: ch is mixed with rem" }` on every key (see
+  [Breakpoints](#breakpoints)); skipped for keys that aren't literals
 
 There is no autocomplete inside a template string, and each template reports
 one problem at a time.
 
 In development, `defineLayout` also runs `validateGridConfig()` once per
 definition and logs what types can't check: areas and layers that aren't
-rectangles, and malformed cells. `validateGridConfig()` returns those
+rectangles, malformed cells, and breakpoint keys that aren't allowed or
+mix units (also when the keys aren't literals). `validateGridConfig()` returns those
 warnings as strings, so it is also useful for definitions assembled
 dynamically.
 
@@ -255,6 +260,16 @@ defineLayout({
 });
 ```
 
+**Every breakpoint of a definition uses one unit**, across all its layouts,
+and the named sizes count as `rem`. An arbitrary key is a plain,
+non-negative number and one of `px`, `rem`, `em`, `ch`, `ex`, `vw`, `vh`,
+`vi` or `vb`: `"@[27.5rem]"`, `"@[40ch]"`. The generated CSS relies on
+breakpoints being ordered by width, and breakpoints in different units can't
+be ordered when it's generated, because how they compare depends on font
+sizes and the viewport. So `"@[20ch]"` next to `"@sm"` is a type error.
+Percentages, `calc()` and container query units (`cqw`, `cqi`, …, which in
+a query measure a container above the grid) aren't allowed either.
+
 A breakpoint arrangement beats its own layout's base arrangement, but a
 later layout still beats an earlier layout's breakpoints. Breakpoint
 arrangements take their own `rows`, `columns` and `align`; nothing is
@@ -358,6 +373,49 @@ The library's own tests only run in Chromium. In older browsers the query
 simply never matches, so write the unlayered look as the default and the
 layered look inside the query.
 
+## Accessibility: reading order
+
+Each layout, and each of its breakpoints, can put the areas in a different
+visual order, but keyboard focus follows the DOM: the order the slots are
+rendered in. One DOM order can't match every layout.
+
+`reading-flow` on the grid makes keyboard focus follow the layout that
+currently applies instead, at every breakpoint. The library doesn't set it:
+give the grid a class of your own.
+
+```css
+.card {
+  reading-flow: grid-rows;
+}
+```
+
+`grid-rows` reads the grid row by row; use `grid-columns` when the design
+reads down its columns first. Put the class on the grid like any other:
+`className` in React, `class` (or `className`) in Preact, `class` in Vue,
+Svelte, Solid and Octane and on the element carrying `[tgaGrid]` in Angular,
+and the grid's `class` option in Lit. With Tailwind, the arbitrary property
+`[reading-flow:grid-rows]` does the same.
+
+- **A progressive enhancement.** Supported in Chrome and Edge 137+; other
+  browsers keep DOM order. So still render the slots in the order that makes
+  sense for the most important layout
+  ([WCAG 1.3.2, Meaningful Sequence](https://www.w3.org/WAI/WCAG22/Understanding/meaningful-sequence.html)),
+  and let `reading-flow` follow the others where it's supported.
+- **Layers.** Slots are read in the order of the cell each starts in. A
+  layer that starts in the same cell as its base ties with it, and a tie
+  falls back to DOM order: render whichever of the two should be read first
+  earlier.
+- **Not `order`.** `order` only moves auto-placed elements, and every slot
+  is placed by its area name, so it moves nothing. It doesn't change focus
+  order either.
+- **Why it isn't built in.** Setting `reading-flow` in the generated CSS
+  would override a DOM order you chose on purpose.
+
+What this gives you is keyboard focus that follows the layout. The CSS
+specification applies `reading-flow` to the reading order passed to
+assistive technology too, but it has been checked for keyboard focus in
+Chromium only, not with screen readers.
+
 ## Rendering with React: grid components
 
 `createGridComponent(definition)` turns a definition into the component it

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typed-grid-areas/solid",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Solid adapter for typed-grid-areas: render a grid definition as typed slot components.",
   "keywords": [
     "css-grid",
@@ -43,7 +43,7 @@
     "solid-js": "^1.9.0"
   },
   "dependencies": {
-    "typed-grid-areas": "^0.3.1"
+    "typed-grid-areas": "^0.4.0"
   },
   "devDependencies": {
     "@typed-grid-areas/acceptance": "*",