@scattered-light/loomiere 0.2.0 → 0.3.0

package/exporters/design-system.mjs

@@ -313,13 +313,72 @@ function brandBook({ theme, brand, byPath, cssName, usageOf, tokens, tiers, styl
     '',
   );
   if (componentNames.length) {
+    const has = (n) => componentNames.includes(n);
+    const pick = (list) => list.filter(([n]) => has(n)).map(([n, use]) => `| \`${n}\` | ${use} |`);
     out.push(
       '## Components',
       '',
-      `The components are [Base UI](https://base-ui.com) parts styled by class name: ${componentNames.map((n) => `\`${n}\``).join(', ')}. Each component's README lists the classes its parts take and the data attributes they answer to (\`data-size="sm|lg"\`, \`data-emphasis\`, \`data-color\`). In previews and designs they are \`window.Loomiere.<Name>\`; Button, Input, Field, Fieldset, Form and NavigationMenu are wrappers that put their classes on themselves.`,
+      `The components are [Base UI](https://base-ui.com) parts styled by class name: ${componentNames.map((n) => `\`${n}\``).join(', ')}. Each component's README lists the classes its parts take and the data attributes they answer to (\`data-size="sm|lg"\`, \`data-emphasis\`, \`data-color\`).`,
       '',
       'Icons are Material Symbols Outlined by ligature name (`<span class="material-symbols-outlined">search</span>`, or `Loomiere.MaterialSymbol name="search"`), sized by the `.icon-<tier>` utilities to match the text beside them.',
       '',
+      '### Using the components in a page or design',
+      '',
+      'Load three things, in this order:',
+      '',
+      '1. `components/bundle.css`: the whole theme in one sheet. It holds every token (light, dark, high contrast and color vision modes), the text style, icon and focus utilities, the brand pairs, and every component\'s styles, and it imports the brand fonts and Material Symbols from Google Fonts itself. Nothing else is needed for styling; `tokens.json` is the same tokens as data for the Design System page.',
+      '2. React 18 and ReactDOM 18 as the `window.React` and `window.ReactDOM` globals. A design canvas or the preview frame already has them.',
+      '3. `components/bundle.js`: one classic script that sets `window.Loomiere`.',
+      '',
+      '`window.Loomiere` holds two kinds of component:',
+      '',
+      `- **Wrappers** put their own classes on, so use them bare: ${['Button', 'IconButton', 'Input', 'Field', 'Fieldset', 'Form', 'NavigationMenu'].filter(has).map((n) => `\`Loomiere.${n}\``).join(', ')}. \`Loomiere.Button\` also takes \`emphasis\` (\`bold|standard|subtle|quiet\`) and \`palette\` props, and a Button holding only an icon draws itself square (it sets \`data-icon-only\`). A plain \`.Button\`, such as a Popover or Toolbar trigger, is drawn square when it has an \`aria-label\` and a single icon inside, or when you set \`data-icon-only\` on it.`,
+      '- **Everything else is the bare Base UI part** under its usual name (`Loomiere.Popover.Popup`, `Loomiere.ToggleGroup`). It draws nothing until you give each part its class, which is the component and part names joined: `<Loomiere.Popover.Popup className="PopoverPopup">`, `<Loomiere.Toggle className="Toggle">`. The component READMEs list every class.',
+      '',
+      '`Loomiere.Base` holds the bare Base UI parts for the wrappers too (`Loomiere.Base.Button`), for when you need the part without its classes.',
+      '',
+      '### Choosing a component',
+      '',
+      'Pick by what the person is doing, not by look:',
+      '',
+      '| Component | Use it to |',
+      '|---|---|',
+      ...pick([
+        ['Button', 'Run one action. Set its emphasis by how much the action matters.'],
+        ['IconButton', 'Run a small, frequent action shown as an icon alone, where a Button would be too loud: calendar arrows, row actions, a clear button. Always give it an aria-label.'],
+        ['Switch', 'Turn one setting on or off, taking effect at once.'],
+        ['Checkbox', 'Turn one option on or off inside a form that is submitted later.'],
+        ['Toggle', 'A tool that stays pressed, such as Bold in a toolbar.'],
+        ['ToggleGroup', 'Switch between 2 to 5 short modes or views that apply at once (Single date / Date range, List / Grid).'],
+        ['Tabs', 'Switch between panels of content in the same place.'],
+        ['Radio', 'Choose one of 2 to 6 options in a form, where each option can carry a label and description.'],
+        ['CheckboxGroup', 'Choose any number of a few visible options.'],
+        ['Select', 'Choose one of a fixed list too long to show (about 6 to 15 items).'],
+        ['Combobox', 'Choose one or more from a long list by typing to filter it.'],
+        ['Autocomplete', 'Type free text, with suggestions to speed it up.'],
+        ['NumberField', 'Enter an exact number, with steppers.'],
+        ['Slider', 'Set a value in a range where roughly is good enough.'],
+        ['OTPField', 'Enter a one-time code.'],
+        ['Menu', 'Offer commands from a button. Menus run actions; they don\'t hold a value.'],
+        ['ContextMenu', 'Offer commands on right-click or long press.'],
+        ['Menubar', 'An app\'s top row of menus.'],
+        ['Toolbar', 'A row of buttons, toggles and fields that act on one thing.'],
+        ['NavigationMenu', 'Site navigation, with panels of links.'],
+        ['Tooltip', 'Name an icon-only control. Never put anything you can click inside one.'],
+        ['PreviewCard', 'Preview what a link leads to on hover.'],
+        ['Popover', 'Show interactive content beside its trigger: a picker, a short form, filters.'],
+        ['Dialog', 'A task that needs full attention before the page goes on.'],
+        ['AlertDialog', 'Confirm a destructive or hard-to-undo action.'],
+        ['Drawer', 'A side task or detail panel that keeps the page in view.'],
+        ['Accordion', 'Several sections where only some need to be open.'],
+        ['Collapsible', 'One section to show or hide.'],
+        ['Toast', 'Report the result of an action, briefly.'],
+        ['Progress', 'Show how far a task has got.'],
+        ['Meter', 'Show a measured amount within known limits, such as storage used.'],
+      ]),
+      '',
+      `A list of choices that stays on screen inside a panel, one of them selected (quick picks, saved filters, presets), has no Base UI part. Make each row a \`<button aria-pressed>\` drawn from the item concept: \`--${theme.prefix}-item-padding-block\`, \`-padding-inline\`, \`-radius\` and \`-gap\`, \`--${theme.prefix}-item-background-hover\` and \`-color-hover\` on hover, \`--${theme.prefix}-item-background-selected\` and \`-color-selected\` with the \`-selected\` text style when chosen. These are the same rows menus and selects use. When the choice is a form value, use Radio instead.`,
+      '',
     );
   }
   return `${out.join('\n')}\n`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scattered-light/loomiere",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Turns a small brand file into a full design token theme: OKLCH color ramps, a type scale, light, dark and high-contrast modes, plus Tailwind, MUI, Chakra, AG Grid and Figma exports.",
   "keywords": ["design-tokens", "theme", "style-dictionary", "dtcg", "oklch", "base-ui", "ag-grid", "tailwind"],
   "repository": {

package/tokens/component/popover.json

@@ -1,9 +1,9 @@
 {
   "popover": {
     "$description": "Popover's own sizes. Everything else is the popup and close concepts, text styles and CSS.",
-    "popup-max-width": {
-      "$value": "400px",
-      "$description": "Keeps longer text to a readable line length."
+    "text-max-width": {
+      "$value": "{measure.narrow}",
+      "$description": "Keeps the title and description to a readable line length. The popup itself has no fixed cap, so wider content such as a calendar or a form fits; it stops at the space Base UI reports beside the trigger."
     },
     "popup-min-width": {
       "$value": "{popup.min-width}",