@wallarm-org/claude-design 0.0.0-stage → 4.8.0

package/dist/project/components/Selection/README.md

@@ -0,0 +1,648 @@
+Turns a set of anything — cards, rows, list items — into a selectable collection: a checkbox on each one, shift-click for a range, and a bulk-action bar that arrives once something is ticked. The selection is controlled and ordered by `items`, so what comes back follows the list rather than the order of clicks, and ids no longer present in `items` are kept rather than dropped — a selection can outlive a page change, and clearing it is the caller's decision. Not for Table rows — a `Table` has its own checkbox column: pass `rowSelection` + `onRowSelectionChange` and put bulk actions in `TableActionBar`.
+
+## Props as canvas attributes
+
+Use kebab-case attribute names. Pass non-string values through renderVals holes, including booleans. The full emitted API is in `components/index.d.ts`.
+
+| Attribute | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `items` | `T[]` | yes | — | Source array — used for select-all and shift-click range ordering. |
+| `get-item-id` | `(item: T) => string` | yes | — | Stable id extractor for items. |
+| `value` | `string[]` | yes | — | Controlled selection state — array of selected item ids. |
+| `on-change` | `(ids: string[]) => void` | yes | — | Called with the next ordered array of selected ids. |
+| `data-testid` | `string \| undefined` | no | — |  |
+
+## Sub-components
+
+- `WallarmDS.SelectionAll` — `SelectionAllProps` in the declaration bundle.
+- `WallarmDS.SelectionBulkBar` — `SelectionBulkBarProps` in the declaration bundle.
+- `WallarmDS.SelectionItem` — `SelectionItemProps` in the declaration bundle.
+
+## Stories
+
+### Default
+
+The shape at its smallest: `Selection` around the collection, a `SelectionItem` per card,
+and a `SelectionBulkBar` that stays out of the way until something is selected.
+
+Source: Selection/Selection.stories.tsx#Default
+
+### WithSelectAll
+
+`SelectionAll` is the header checkbox — indeterminate while the selection is partial, and
+a press while everything is selected clears it rather than reselecting.
+
+Source: Selection/Selection.stories.tsx#WithSelectAll
+
+### Grid
+
+The same machinery over a three-column grid: `Selection` lays nothing out, so the
+arrangement stays entirely yours.
+
+Source: Selection/Selection.stories.tsx#Grid
+
+### WithDisabled
+
+A `disabled` item leaves both select-all and any shift range, so "all" means all the ones
+this user is allowed to touch — and the header checkbox counts only those.
+
+Source: Selection/Selection.stories.tsx#WithDisabled
+
+### RangeSelection
+
+Shift-click selects everything between the last checkbox you touched and this one,
+following the order of `items` rather than the order you clicked in.
+
+Source: Selection/Selection.stories.tsx#RangeSelection
+
+### BulkActions
+
+Three actions in one bar. Only the destructive one is solid, so a bar with several verbs
+still has a single obvious primary.
+
+Source: Selection/Selection.stories.tsx#BulkActions
+
+### EmptyAndPartial
+
+Emptying the list strands the ids that were selected, because the component keeps them on
+purpose — the effect here is the cleanup pattern, dropping any id the list no longer has.
+
+Source: Selection/Selection.stories.tsx#EmptyAndPartial
+
+### WithoutBulkBar
+
+No bar at all: the selection still works and the count is rendered from state, for a page
+that acts on the selection somewhere else entirely.
+
+Source: Selection/Selection.stories.tsx#WithoutBulkBar
+
+### CompoundBulkBar
+
+Composing the summary — count, select-all, clear — instead of taking the default. It has
+to be a direct child of the bar; a wrapper component hides it and the default appears too.
+
+Source: Selection/Selection.stories.tsx#CompoundBulkBar
+
+### InsideDrawer
+
+Inside a `Drawer`, `placement='absolute'` pins the bar to the bottom of the panel instead
+of the viewport, and the actions step up to `large` to match the surface.
+
+Source: Selection/Selection.stories.tsx#InsideDrawer
+
+## Story sources
+
+### Selection/Selection.stories.tsx
+
+```tsx
+import { useEffect, useState } from 'react';
+import { fn } from 'storybook/test';
+import type { Meta, StoryFn } from 'storybook-react-rsbuild';
+import { Copy, Folder, Trash2 } from '../../icons';
+import { Badge } from '../Badge';
+import {
+  BulkBarSummary,
+  BulkBarSummaryClear,
+  BulkBarSummaryCount,
+  BulkBarSummarySelectAll,
+  BulkBarSummarySeparator,
+} from '../BulkBar';
+import { Button } from '../Button';
+import { Card, CardContent, CardFooter, CardHeader, CardTitle } from '../Card';
+import {
+  Drawer,
+  DrawerBody,
+  DrawerContent,
+  DrawerHeader,
+  DrawerResizeHandle,
+  DrawerTitle,
+  DrawerTrigger,
+} from '../Drawer';
+import { HStack, VStack } from '../Stack';
+import { Text } from '../Text';
+import { Selection } from './Selection';
+import { SelectionAll } from './SelectionAll';
+import { SelectionBulkBar } from './SelectionBulkBar';
+import { SelectionItem } from './SelectionItem';
+import { useSelectionContext } from './useSelectionContext';
+
+interface Cluster {
+  id: string;
+  title: string;
+  region: string;
+  status: 'Active' | 'Idle' | 'Error';
+  locked?: boolean;
+}
+
+const clusters: Cluster[] = [
+  { id: '1', title: 'Production cluster', region: 'us-east-1', status: 'Active' },
+  { id: '2', title: 'Staging cluster', region: 'eu-west-1', status: 'Active' },
+  { id: '3', title: 'Dev cluster', region: 'us-west-2', status: 'Idle' },
+  { id: '4', title: 'Legacy cluster', region: 'ap-south-1', status: 'Error' },
+  { id: '5', title: 'Read replica', region: 'us-east-1', status: 'Active', locked: true },
+];
+
+const onDuplicate = fn().mockName('onDuplicate');
+const onDelete = fn().mockName('onDelete');
+const onMove = fn().mockName('onMove');
+const onInspect = fn().mockName('onInspect');
+const onConfirm = fn().mockName('onConfirm');
+
+const DESCRIPTION = [
+  'Turns a set of anything — cards, rows, list items — into a selectable collection: a checkbox on each one, shift-click for a range, and a bulk-action bar that arrives once something is ticked.',
+  "The selection is controlled and ordered by `items`, so what comes back follows the list rather than the order of clicks, and ids no longer present in `items` are kept rather than dropped — a selection can outlive a page change, and clearing it is the caller's decision.",
+  'Not for Table rows — a `Table` has its own checkbox column: pass `rowSelection` + `onRowSelectionChange` and put bulk actions in `TableActionBar`.',
+].join(' ');
+
+const meta = {
+  title: 'Data Display/Selection',
+  component: Selection,
+  subcomponents: {
+    SelectionItem,
+    SelectionAll,
+    SelectionBulkBar,
+  },
+  parameters: {
+    layout: 'padded',
+    docs: { description: { component: DESCRIPTION } },
+  },
+} satisfies Meta<typeof Selection>;
+
+export default meta;
+
+const ClusterCard = ({ cluster }: { cluster: Cluster }) => (
+  <Card className='flex-1'>
+    <CardHeader>
+      <CardTitle>{cluster.title}</CardTitle>
+    </CardHeader>
+    <CardContent>
+      <Text size='sm' color='secondary'>
+        {cluster.region}
+      </Text>
+    </CardContent>
+    <CardFooter>
+      <Badge>{cluster.status}</Badge>
+    </CardFooter>
+  </Card>
+);
+
+/**
+ * The shape at its smallest: `Selection` around the collection, a `SelectionItem` per card,
+ * and a `SelectionBulkBar` that stays out of the way until something is selected.
+ */
+export const Default: StoryFn<typeof meta> = () => {
+  const [selected, setSelected] = useState<string[]>([]);
+
+  return (
+    <Selection
+      data-testid='selection'
+      items={clusters}
+      getItemId={c => c.id}
+      value={selected}
+      onChange={setSelected}
+    >
+      <VStack gap={12}>
+        {clusters.map(c => (
+          <SelectionItem key={c.id} itemId={c.id}>
+            <ClusterCard cluster={c} />
+          </SelectionItem>
+        ))}
+      </VStack>
+
+      <SelectionBulkBar>
+        <Button variant='ghost' color='neutral-alt' onClick={() => onDuplicate(selected)}>
+          <Copy /> Duplicate
+        </Button>
+        <Button color='brand' onClick={() => onDelete(selected)}>
+          <Trash2 /> Delete
+        </Button>
+      </SelectionBulkBar>
+    </Selection>
+  );
+};
+
+/**
+ * `SelectionAll` is the header checkbox — indeterminate while the selection is partial, and
+ * a press while everything is selected clears it rather than reselecting.
+ */
+export const WithSelectAll: StoryFn<typeof meta> = () => {
+  const [selected, setSelected] = useState<string[]>([]);
+
+  return (
+    <Selection
+      data-testid='selection'
+      items={clusters}
+      getItemId={c => c.id}
+      value={selected}
+      onChange={setSelected}
+    >
+      <VStack gap={16}>
+        <HStack gap={8} align='center'>
+          <SelectionAll />
+          <Text size='sm' color='secondary'>
+            Select all
+          </Text>
+        </HStack>
+
+        <VStack gap={12}>
+          {clusters.map(c => (
+            <SelectionItem key={c.id} itemId={c.id}>
+              <ClusterCard cluster={c} />
+            </SelectionItem>
+          ))}
+        </VStack>
+      </VStack>
+
+      <SelectionBulkBar>
+        <Button color='brand' onClick={() => onDelete(selected)}>
+          <Trash2 /> Delete
+        </Button>
+      </SelectionBulkBar>
+    </Selection>
+  );
+};
+
+/**
+ * The same machinery over a three-column grid: `Selection` lays nothing out, so the
+ * arrangement stays entirely yours.
+ */
+export const Grid: StoryFn<typeof meta> = () => {
+  const [selected, setSelected] = useState<string[]>([]);
+
+  return (
+    <Selection
+      data-testid='selection'
+      items={clusters}
+      getItemId={c => c.id}
+      value={selected}
+      onChange={setSelected}
+    >
+      <div className='grid grid-cols-3 gap-12'>
+        {clusters.map(c => (
+          <SelectionItem key={c.id} itemId={c.id}>
+            <ClusterCard cluster={c} />
+          </SelectionItem>
+        ))}
+      </div>
+
+      <SelectionBulkBar>
+        <Button onClick={() => onInspect(selected)}>Inspect</Button>
+      </SelectionBulkBar>
+    </Selection>
+  );
+};
+
+/**
+ * A `disabled` item leaves both select-all and any shift range, so "all" means all the ones
+ * this user is allowed to touch — and the header checkbox counts only those.
+ */
+export const WithDisabled: StoryFn<typeof meta> = () => {
+  const [selected, setSelected] = useState<string[]>([]);
+
+  return (
+    <Selection
+      data-testid='selection'
+      items={clusters}
+      getItemId={c => c.id}
+      value={selected}
+      onChange={setSelected}
+    >
+      <VStack gap={8}>
+        <HStack gap={8} align='center'>
+          <SelectionAll />
+          <Text size='sm' color='secondary'>
+            Select all (locked items skipped)
+          </Text>
+        </HStack>
+
+        <VStack gap={12}>
+          {clusters.map(c => (
+            <SelectionItem key={c.id} itemId={c.id} disabled={c.locked}>
+              <ClusterCard cluster={c} />
+            </SelectionItem>
+          ))}
+        </VStack>
+      </VStack>
+
+      <SelectionBulkBar>
+        <Button color='brand' onClick={() => onDelete(selected)}>
+          <Trash2 /> Delete
+        </Button>
+      </SelectionBulkBar>
+    </Selection>
+  );
+};
+
+/**
+ * Shift-click selects everything between the last checkbox you touched and this one,
+ * following the order of `items` rather than the order you clicked in.
+ */
+export const RangeSelection: StoryFn<typeof meta> = () => {
+  const [selected, setSelected] = useState<string[]>([]);
+
+  return (
+    <Selection
+      data-testid='selection'
+      items={clusters}
+      getItemId={c => c.id}
+      value={selected}
+      onChange={setSelected}
+    >
+      <VStack gap={12}>
+        <span className='sb-annotation'>hold shift and click another checkbox</span>
+        {clusters.map(c => (
+          <SelectionItem key={c.id} itemId={c.id}>
+            <ClusterCard cluster={c} />
+          </SelectionItem>
+        ))}
+      </VStack>
+
+      <SelectionBulkBar>
+        <Button color='brand' onClick={() => onConfirm(selected)}>
+          Confirm
+        </Button>
+      </SelectionBulkBar>
+    </Selection>
+  );
+};
+
+/**
+ * Three actions in one bar. Only the destructive one is solid, so a bar with several verbs
+ * still has a single obvious primary.
+ */
+export const BulkActions: StoryFn<typeof meta> = () => {
+  const [selected, setSelected] = useState<string[]>([]);
+
+  return (
+    <Selection
+      data-testid='selection'
+      items={clusters}
+      getItemId={c => c.id}
+      value={selected}
+      onChange={setSelected}
+    >
+      <VStack gap={12}>
+        {clusters.map(c => (
+          <SelectionItem key={c.id} itemId={c.id}>
+            <ClusterCard cluster={c} />
+          </SelectionItem>
+        ))}
+      </VStack>
+
+      <SelectionBulkBar>
+        <Button variant='ghost' color='neutral-alt' onClick={() => onMove(selected)}>
+          <Folder /> Move
+        </Button>
+        <Button variant='ghost' color='neutral-alt' onClick={() => onDuplicate(selected)}>
+          <Copy /> Duplicate
+        </Button>
+        <Button color='brand' onClick={() => onDelete(selected)}>
+          <Trash2 /> Delete
+        </Button>
+      </SelectionBulkBar>
+    </Selection>
+  );
+};
+
+/**
+ * Emptying the list strands the ids that were selected, because the component keeps them on
+ * purpose — the effect here is the cleanup pattern, dropping any id the list no longer has.
+ */
+export const EmptyAndPartial: StoryFn<typeof meta> = () => {
+  const [items, setItems] = useState<Cluster[]>(clusters);
+  const [selected, setSelected] = useState<string[]>(['1', 'ghost']);
+
+  // Demonstrate cleanup pattern: drop ids that no longer exist in items.
+  useEffect(() => {
+    setSelected(prev => prev.filter(id => items.some(c => c.id === id)));
+  }, [items]);
+
+  return (
+    <VStack gap={16}>
+      <HStack gap={8}>
+        <Button onClick={() => setItems([])} variant='outline'>
+          Clear items
+        </Button>
+        <Button onClick={() => setItems(clusters)} variant='outline'>
+          Restore items
+        </Button>
+      </HStack>
+
+      <Selection
+        data-testid='selection'
+        items={items}
+        getItemId={c => c.id}
+        value={selected}
+        onChange={setSelected}
+      >
+        <VStack gap={12}>
+          {items.length === 0 ? (
+            <Text size='sm' color='secondary'>
+              No items.
+            </Text>
+          ) : (
+            items.map(c => (
+              <SelectionItem key={c.id} itemId={c.id}>
+                <ClusterCard cluster={c} />
+              </SelectionItem>
+            ))
+          )}
+        </VStack>
+
+        <SelectionBulkBar>
+          <Button color='brand' onClick={() => onDelete(selected)}>
+            <Trash2 /> Delete
+          </Button>
+        </SelectionBulkBar>
+      </Selection>
+    </VStack>
+  );
+};
+
+/**
+ * No bar at all: the selection still works and the count is rendered from state, for a page
+ * that acts on the selection somewhere else entirely.
+ */
+export const WithoutBulkBar: StoryFn<typeof meta> = () => {
+  const [selected, setSelected] = useState<string[]>([]);
+
+  return (
+    <Selection
+      data-testid='selection'
+      items={clusters}
+      getItemId={c => c.id}
+      value={selected}
+      onChange={setSelected}
+    >
+      <VStack gap={16}>
+        <Text size='sm' color='secondary'>
+          Selected: {selected.length}
+        </Text>
+
+        <VStack gap={12}>
+          {clusters.map(c => (
+            <SelectionItem key={c.id} itemId={c.id}>
+              <ClusterCard cluster={c} />
+            </SelectionItem>
+          ))}
+        </VStack>
+      </VStack>
+    </Selection>
+  );
+};
+
+// `partitionChildren` inside SelectionBulkBar matches `<BulkBarSummary>` by
+// React element type, so the summary must be a direct JSX child of
+// SelectionBulkBar — wrapper components are opaque and would force the
+// default Selection-wired summary to render alongside.
+const CompoundToolbar = ({ onDeleteSelected }: { onDeleteSelected: (ids: string[]) => void }) => {
+  const { selectedIds, isAllSelected, selectAll, clear } = useSelectionContext();
+
+  return (
+    <SelectionBulkBar placement='absolute' data-testid='selection-bulk-bar'>
+      <BulkBarSummary data-testid='bulk-summary'>
+        <BulkBarSummaryCount count={selectedIds.size} data-testid='bulk-count' />
+        <HStack gap={6}>
+          <BulkBarSummarySelectAll
+            data-testid='bulk-select-all'
+            data-analytics-id='BULK_SELECT_ALL'
+            onClick={selectAll}
+            disabled={isAllSelected}
+          />
+          <BulkBarSummarySeparator />
+          <BulkBarSummaryClear
+            data-testid='bulk-clear'
+            data-analytics-id='BULK_CLEAR'
+            onClick={clear}
+          />
+        </HStack>
+      </BulkBarSummary>
+      <Button
+        data-testid='bulk-delete'
+        data-analytics-id='BULK_DELETE'
+        color='brand'
+        onClick={() => {
+          const ids = [...selectedIds];
+          onDelete(ids);
+          onDeleteSelected(ids);
+        }}
+      >
+        <Trash2 /> Delete
+      </Button>
+    </SelectionBulkBar>
+  );
+};
+
+/**
+ * Composing the summary — count, select-all, clear — instead of taking the default. It has
+ * to be a direct child of the bar; a wrapper component hides it and the default appears too.
+ */
+export const CompoundBulkBar: StoryFn<typeof meta> = () => {
+  const [items, setItems] = useState<Cluster[]>(clusters);
+  const [selected, setSelected] = useState<string[]>([]);
+
+  // Delete actually deletes here: a bulk action that only logged left nothing to
+  // observe, and the row leaving is the honest demonstration of one.
+  const deleteSelected = (ids: string[]) => {
+    setItems(prev => prev.filter(c => !ids.includes(c.id)));
+    setSelected([]);
+  };
+
+  return (
+    <Selection
+      data-testid='selection'
+      items={items}
+      getItemId={c => c.id}
+      value={selected}
+      onChange={setSelected}
+    >
+      <VStack gap={12}>
+        {items.map(c => (
+          <SelectionItem key={c.id} itemId={c.id}>
+            <ClusterCard cluster={c} />
+          </SelectionItem>
+        ))}
+      </VStack>
+
+      <CompoundToolbar onDeleteSelected={deleteSelected} />
+    </Selection>
+  );
+};
+
+/**
+ * Inside a `Drawer`, `placement='absolute'` pins the bar to the bottom of the panel instead
+ * of the viewport, and the actions step up to `large` to match the surface.
+ */
+export const InsideDrawer: StoryFn<typeof meta> = () => {
+  const [selected, setSelected] = useState<string[]>([]);
+
+  return (
+    <Drawer width={720}>
+      <DrawerTrigger asChild>
+        <Button variant='outline' color='neutral'>
+          Open drawer with selection
+        </Button>
+      </DrawerTrigger>
+      <DrawerContent>
+        <Selection
+          items={clusters}
+          getItemId={c => c.id}
+          value={selected}
+          onChange={setSelected}
+          className='flex min-h-0 flex-1 flex-col'
+        >
+          <DrawerResizeHandle />
+          <DrawerHeader>
+            <DrawerTitle>Clusters</DrawerTitle>
+          </DrawerHeader>
+          <DrawerBody>
+            <VStack gap={16}>
+              <HStack gap={8} align='center'>
+                <SelectionAll />
+                <Text size='sm' color='secondary'>
+                  Select all
+                </Text>
+              </HStack>
+
+              <VStack gap={12}>
+                {clusters.map(c => (
+                  <SelectionItem key={c.id} itemId={c.id}>
+                    <ClusterCard cluster={c} />
+                  </SelectionItem>
+                ))}
+              </VStack>
+            </VStack>
+          </DrawerBody>
+
+          <SelectionBulkBar placement='absolute'>
+            <Button
+              variant='secondary'
+              color='neutral-alt'
+              size='large'
+              onClick={() => onDuplicate(selected)}
+            >
+              <Copy /> Duplicate
+            </Button>
+            <Button
+              variant='secondary'
+              color='neutral-alt'
+              size='large'
+              onClick={() => onMove(selected)}
+            >
+              <Folder /> Move
+            </Button>
+            <Button
+              variant='secondary'
+              color='destructive'
+              size='large'
+              onClick={() => onDelete(selected)}
+            >
+              <Trash2 /> Delete
+            </Button>
+          </SelectionBulkBar>
+        </Selection>
+      </DrawerContent>
+    </Drawer>
+  );
+};
+```

package/dist/project/components/Selection/preview.html

@@ -0,0 +1,2 @@
+<!-- @dsCard group="Data Display" height=480 -->
+<!doctype html><html><head><meta charset="utf-8"></head><body><div id="preview"></div><script src="./stories.js"></script><script>window.WallarmPreview.mount(document.getElementById('preview'));</script></body></html>