@scattered-light/loomiere-base-ui 0.6.1 → 0.7.1

package/dist/design-system/components/EmptyState/README.md

@@ -0,0 +1,60 @@
+# EmptyState
+
+Loomiere component, not part of Base UI. The block a page, pane, table, list or popup shows when it has nothing to show. One look for every kind. data-kind only picks the media tone and, in the component, the default icon and whether the block is announced. Sizes are empty.* (tokens/semantic/empty.json). No border and no fill: the container provides those. The circle uses the subtle emphasis level (--sl-e-bg, --sl-e-fg), the same variables Badge uses. data-status on the media recolors it. A parent data-color does too: the subtle chrome pin skips this circle when a color scope is on an ancestor (Badge keeps the pin). A brand pair re-points fill and text, not that chrome scope. The circle stays chrome subtle inside a pair, the same as Badge, so a pair does not get its own selector. High contrast and the vision themes come with those variables. The title stays text-primary and the description text-secondary: an error's title is not red, because a sentence has to stay readable. Neutral kinds use the chrome palette, which is what subtle resolves to when no status is set. Text is a whole style per size, not a font-size on its own. Compact is a table row or a popup, so the title is subtitle-condense (bold, the row's size) and the description is body-condense. Standard is a pane: title-condense, the section heading, with body-base under it. Spacious is a page: title-magnify, the next title up, still body-base so the sentence doesn't grow with the heading. Unselected is the quiet pane beside a list, so it drops the circle, the icon is text-tertiary, and the title steps down one tier: subtitle-minimize where the others use a condense style (there is no title at minimize), and title-condense where the others use title-magnify. Compact is a row (icon, text, actions) centered across the cell. Standard and spacious are a column. They take margin-block: auto so a flex or grid column centers them in the leftover space; in normal flow that margin is zero, so a page that isn't a column doesn't grow a hole. There is no data-fill attribute. The icon for unselected is left_click: the pane is waiting for a choice in the list beside it, which an empty inbox would not say. A popup's empty slot already pads a plain sentence (popup-empty). When the child is an EmptyState, that padding drops so the two don't add. Menu.Empty has no popup-empty padding of its own, so it needs nothing here.
+
+Use `Loomiere.EmptyState`, this package's component: it puts the class names on for you (`import { EmptyState } from '@scattered-light/loomiere-base-ui'`, or from `@scattered-light/loomiere-base-ui/custom`).
+
+Not a Base UI part, so there is no base-ui.com page for it.
+
+## Classes
+
+| Class | Data attributes it answers to |
+|---|---|
+| `EmptyState` | `data-size`: `compact`, `spacious`, `standard`; `data-kind`: `unselected` |
+| `EmptyStateMedia` | `data-custom` |
+| `EmptyStateText` |   |
+| `EmptyStateTitle` |   |
+| `EmptyStateDescription` |   |
+| `EmptyStateActions` |   |
+| `ComboboxEmpty` |   |
+| `AutocompleteEmpty` |   |
+
+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 EmptyState stories (`Default`):
+
+```tsx
+export const Default: Story = {
+  render: () => (
+    <table className="Table">
+      <thead>
+        <tr>
+          <th scope="col">Payee</th>
+          <th scope="col">Date</th>
+          <th scope="col" data-align="end">Amount</th>
+          <th scope="col">Status</th>
+        </tr>
+      </thead>
+      <tbody>
+        <tr>
+          <td data-empty colSpan={4}>
+            <EmptyState
+              size="compact"
+              kind="no-results"
+              title="No transactions match"
+              description="Try a different date range, or clear the filters."
+              actions={<Button emphasis="standard">Clear filters</Button>}
+            />
+          </td>
+        </tr>
+      </tbody>
+    </table>
+  ),
+};
+
+/** Starts with rows. Filtering to nothing announces the no-results title once. */
+```
+
+The preview also shows `AfterFilter`, `Start`, `NoResults`.