@weasel-js/prefs 1.10.1 → 1.11.0

package/README.md

@@ -42,6 +42,27 @@ It takes an adapter that reads synchronously, and components naming the same
 `storage` and `prefix` with different schemas each get a store over the same
 records.
 
+## Tags
+
+A leaf, a group, and a section can each carry `tags`: words a settings search
+also finds it by, and that gather it with others. A leaf carries its own and
+every group's above it, so tagging a group tags all it holds:
+
+```ts
+canvas: { name: 'Canvas', tags: ['workspace'], children: {
+  grid: { kind: 'boolean', name: 'Show grid', description: '', default: true, tags: ['guides'] },
+} },
+
+prefLeavesTagged(SCHEMA, 'guides');      // Map { 'canvas.grid' => … }
+prefLeafTags(SCHEMA, 'canvas.grid');     // ['workspace', 'guides']
+filterPrefSubtree(SCHEMA, 'guide');      // keeps canvas.grid, matched by its tag
+```
+
+A search matches a tag as it matches a name, and a group a tag matches keeps
+all its leaves, as one its name matches does. An alias carries its target's
+tags and its own. `tags` is unrelated to a `union` leaf's `tag`, the field its
+value's variant is read from.
+
 ## Ranges
 
 A number leaf's range is one scale: the low end is the least of what its label
@@ -52,6 +73,15 @@ a 0–100% limit is off at 100, and a scale with no such end takes `endless`,
 which adds a stop one step past the range that stores `Infinity` and reads the
 leaf's `infinity` word.
 
+A bound that depends on where the value is held takes `minAt` or `maxAt`: a
+function handed a reader of the values beside it, by the paths a condition
+there would name, returning the bound or `undefined`. It is taken with `min`
+or `max`, the tighter winning, and `prefNumberAt(leaf, read)` folds it in for
+one holder. A box's width that may not go under its node's own minimum reads
+`data.minSize` this way: `SelectionPanel` resolves it against each node and
+holds each write to that node's bound, and `PrefsForm` and labkit's
+`ControlPanel` resolve it against their values.
+
 ## Split values
 
 A leaf that lists `splitBy` may hold its value once per option of another
@@ -135,3 +165,24 @@ come later. A number is written in its display unit where the unit's suffix is
 a CSS unit, a boolean as `1` or `0`, an enum's option as an identifier, and a
 string quoted; a leaf of any other kind is left out unless the `value` option
 writes it. `root`, `property`, and `attribute` rename what it writes.
+
+`prefsDefaultsSource(schema)` stands in for a store at its defaults, so
+`prefsCss(prefsDefaultsSource(schema))` is a schema's stylesheet with no store.
+The Vite plugin in `@weasel-js/prefs/vite` serves that sheet for every schema
+you name, by module and export, and rewrites it when a schema changes:
+
+```ts
+// vite.config.ts
+import { weaselPrefsCss } from '@weasel-js/prefs/vite';
+export default { plugins: [weaselPrefsCss({ schemas: { './src/prefs.ts': 'SCHEMA' } })] };
+
+// main.ts
+import 'virtual:weasel-prefs.css';
+```
+
+For the kit's own settings, `<KitSettingsFromPrefs store at="kit">` in
+`@weasel-js/prefs/react` hands the store's values under `kit` to
+`KitSettingsProvider`, so `useKitSetting('tree.typeaheadMs')` reads the user's
+value. With `css`, it also writes that subtree as `--wzl-kit-*` properties into
+the document or shadow root it renders in, and keeps them current as the store
+changes; `kitSettingsCssOptions(at)` is the naming it uses.