@scattered-light/loomiere-mojave 0.24.0 → 0.25.0

package/dist/exports/design-system/components/ParameterBar/README.md

@@ -0,0 +1,68 @@
+# ParameterBar
+
+The Base UI ParameterBar styled by the theme. Settings for a result, in one wrapping row on the tray: the app's fields at the start, the status line, the Run button and any extra actions at the end. Fields align on their controls (align-items: flex-end), so a field with a description does not push its neighbours' inputs down. When the bar is narrow the end group wraps onto its own line, at the start. data-changed (a setting changed since the last run) turns the status line to the warning text color. The bar itself does not dim anything; the app dims its own stale result. ParameterBarLocked is a fixed setting: the field label over the value as text with a lock, on no box, at the control's height so it lines up with the inputs beside it.
+
+Use `Loomiere.ParameterBar` (`import { ParameterBar } from '@base-ui/react/parameter-bar'` in an app) and give each part the class below; the styles target those classes, not Base UI's own markup.
+
+Base UI docs: https://base-ui.com/react/components/parameter-bar
+
+## Classes
+
+| Class | Data attributes it answers to |
+|---|---|
+| `ParameterBar` | `data-changed` |
+| `ParameterBarFields` |   |
+| `FieldRoot` |   |
+| `ParameterBarEnd` |   |
+| `ParameterBarStatus` |   |
+| `ParameterBarLocked` |   |
+| `ParameterBarLockedValue` |   |
+| `ParameterBarLockedText` |   |
+
+Base UI sets the state attributes (`data-checked`, `data-open`, `data-disabled`...) itself. Set `data-size`, `data-emphasis`, `data-variant` and `data-color` yourself; `data-color` takes any palette name (`primary`, `secondary`, `error`...) and repaints the part in it.
+
+## Example
+
+From the ParameterBar stories (`Default`):
+
+```tsx
+export const Default: Story = {
+  args: { label: 'Report settings', onRun: () => undefined },
+  render: function Render() {
+    const [asOf, setAsOf] = React.useState('2026-10-31');
+    const [ran, setRan] = React.useState<string | null>(null);
+    const changed = ran !== null && ran !== asOf;
+    return (
+      <div style={{ display: 'grid', gap: 'var(--sl-space-4)' }}>
+        <ParameterBar
+          label="Report settings"
+          onRun={() => setRan(asOf)}
+          runLabel="Run"
+          changed={changed}
+          status={ran === null ? 'Not run yet' : `Ran for ${ran}`}
+        >
+          <Field.Root>
+            <Field.Label>As of</Field.Label>
+            <Input type="date" value={asOf} onChange={(event) => setAsOf(event.target.value)} />
+          </Field.Root>
+          <Field.Root>
+            <Field.Label>Minimum amount</Field.Label>
+            <Input inputMode="decimal" placeholder="No minimum" />
+          </Field.Root>
+        </ParameterBar>
+        <div style={{ opacity: changed ? 0.5 : 1 }}>{ran ? `Balance Sheet as of ${ran}` : 'The report appears here.'}</div>
+      </div>
+    );
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByRole('status')).toHaveTextContent('Not run yet');
+    await userEvent.click(canvas.getByRole('button', { name: 'Run' }));
+    await expect(canvas.getByRole('status')).toHaveTextContent('Ran for 2026-10-31');
+  },
+};
+
+/** A setting the page fixes, such as an Entity report locked to its Entity: text with a lock, not a disabled control. */
+```
+
+The preview also shows `LockedField`, `Narrow`.