@arbor-education/design-system.components 0.15.0 → 0.16.1

package/src/components/table/columnFilters/BooleanFilter.stories.tsx

@@ -0,0 +1,268 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import {
+  Controls,
+  Heading as DocHeading,
+  Markdown,
+  Primary as DocPrimary,
+  Stories,
+  Subtitle,
+  Title,
+} from '@storybook/addon-docs/blocks';
+import { fn } from 'storybook/test';
+import { BooleanFilter, doesBooleanFilterPass } from './BooleanFilter/BooleanFilter';
+import { Table } from 'Components/table/Table';
+
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = [
+  '`BooleanFilter` is an AG Grid column filter component for boolean columns.',
+  'It renders a radio group with three options — **Yes**, **No**, and **Not set** —',
+  'and calls `onModelChange` with a `{ allowTrue, allowFalse }` model whenever the selection changes.',
+  '',
+  'Register it via the AG Grid `filter` column definition property alongside `doesBooleanFilterPass`.',
+].join('\n');
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- On boolean columns (active/inactive, yes/no flags) that need a user-friendly filter UI',
+  '- When you want a three-state filter: show all `true`, show all `false`, or show everything',
+  '',
+  '---',
+  '',
+  '### Registration',
+  '',
+  '```tsx',
+  "import { BooleanFilter, doesBooleanFilterPass } from '@arbor-education/design-system.components';",
+  '',
+  'const colDefs = [',
+  '  {',
+  "    field: 'isActive',",
+  '    filter: { component: BooleanFilter, doesFilterPass: doesBooleanFilterPass },',
+  '  },',
+  '];',
+  '```',
+  '',
+  '---',
+  '',
+  '### Filter model',
+  '',
+  '```ts',
+  'type BooleanFilterModel = {',
+  '  allowTrue: boolean;',
+  '  allowFalse: boolean;',
+  '};',
+  '',
+  '// Yes selected:    { allowTrue: true,  allowFalse: false }',
+  '// No selected:     { allowTrue: false, allowFalse: true  }',
+  '// Not set / All:   { allowTrue: true,  allowFalse: true  }',
+  '```',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[Table](?path=/docs/components-table--docs) · [TimeFilter](?path=/docs/components-table-columnfilters-timefilter--docs)',
+].join('\n');
+
+const PROPS_INTRO = 'The preview below is interactive — click the radio buttons to see the filter model update in the **Actions** panel.';
+
+// ---------------------------------------------------------------------------
+// Custom DocsPage
+// ---------------------------------------------------------------------------
+
+function BooleanFilterDocsPage() {
+  return (
+    <>
+      <Title />
+      <Subtitle />
+      <Markdown>{DESCRIPTION_INTRO}</Markdown>
+      <DocHeading>Interactive example</DocHeading>
+      <Markdown>{PROPS_INTRO}</Markdown>
+      <DocPrimary />
+      <Controls />
+      <DocHeading>Usage guidance</DocHeading>
+      <Markdown>{USAGE_GUIDANCE}</Markdown>
+      <DocHeading>Examples</DocHeading>
+      <Stories title="" />
+      <Markdown>{RELATED_COMPONENTS}</Markdown>
+    </>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Meta
+// ---------------------------------------------------------------------------
+
+const meta = {
+  title: 'Components/Table/ColumnFilters/BooleanFilter',
+  component: BooleanFilter,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: { page: BooleanFilterDocsPage },
+  },
+  argTypes: {
+    model: {
+      description: 'The current filter model. `null` means no filter is active (same as Not set). Pass `{ allowTrue, allowFalse }` to set a specific state.',
+      control: false,
+      table: { type: { summary: '{ allowTrue: boolean; allowFalse: boolean } | null' }, defaultValue: { summary: 'null' } },
+    },
+    onModelChange: {
+      description: 'Called whenever the user changes the filter selection. Receives the new `{ allowTrue, allowFalse }` model.',
+      control: false,
+      table: { type: { summary: '(model: BooleanFilterModel) => void' } },
+    },
+  },
+  args: {
+    onModelChange: fn(),
+  },
+} satisfies Meta<typeof BooleanFilter>;
+
+export default meta;
+type Story = StoryObj<typeof BooleanFilter>;
+
+const withDescription = (story: Story, description: string): Story => ({
+  ...story,
+  parameters: {
+    ...story.parameters,
+    docs: { ...story.parameters?.docs, description: { story: description } },
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+export const Default: Story = withDescription(
+  {
+    args: {
+      model: null,
+      onModelChange: fn(),
+    },
+  },
+  'No active filter (`model: null`) — all three options visible, **Not set** selected by default.',
+);
+
+export const YesSelected: Story = withDescription(
+  {
+    parameters: { controls: { disable: true } },
+    args: {
+      model: { allowTrue: true, allowFalse: false },
+      onModelChange: fn(),
+    },
+  },
+  '**Yes** selected — filter model is `{ allowTrue: true, allowFalse: false }`. Only rows with `true` in this column pass the filter.',
+);
+
+export const NoSelected: Story = withDescription(
+  {
+    parameters: { controls: { disable: true } },
+    args: {
+      model: { allowTrue: false, allowFalse: true },
+      onModelChange: fn(),
+    },
+  },
+  '**No** selected — filter model is `{ allowTrue: false, allowFalse: true }`. Only rows with `false` in this column pass the filter.',
+);
+
+export const Controlled: Story = withDescription(
+  {
+    parameters: { controls: { disable: true } },
+    render: () => {
+      const [model, setModel] = React.useState<{ allowTrue: boolean; allowFalse: boolean } | null>(null);
+      return (
+        <div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>
+          <BooleanFilter model={model} onModelChange={setModel} />
+          <pre style={{ fontSize: '12px', background: 'var(--color-neutral-50)', padding: '8px', borderRadius: '4px' }}>
+            {JSON.stringify(model, null, 2) ?? 'null'}
+          </pre>
+        </div>
+      );
+    },
+  },
+  'Fully controlled — the current model is rendered below the filter as JSON. Click the radio buttons to see the model update.',
+);
+
+const BOOLEAN_FILTER_IN_TABLE_DATA = [
+  { name: 'Alice Johnson', active: true },
+  { name: 'Bob Smith', active: false },
+  { name: 'Charlie Brown', active: true },
+  { name: 'Diana Prince', active: false },
+  { name: 'Ethan Hunt', active: true },
+];
+
+export const InATable: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import {
+  Table,
+  BooleanFilter,
+  doesBooleanFilterPass,
+} from '@arbor-education/design-system.components';
+
+const rowData = [
+  { name: 'Alice Johnson', active: true },
+  { name: 'Bob Smith', active: false },
+  { name: 'Charlie Brown', active: true },
+  { name: 'Diana Prince', active: false },
+  { name: 'Ethan Hunt', active: true },
+];
+
+function BooleanFilterExample() {
+  return (
+    <Table
+      rowData={rowData}
+      columnDefs={[
+        { field: 'name', headerName: 'Name', flex: 2 },
+        {
+          field: 'active',
+          headerName: 'Active',
+          flex: 1,
+          editable: false,
+          cellRenderer: 'dsBooleanCellRenderer',
+          filter: { component: BooleanFilter, doesFilterPass: doesBooleanFilterPass },
+          suppressHeaderFilterButton: false,
+        },
+      ]}
+      defaultColDef={{ flex: 1, minWidth: 120, suppressHeaderFilterButton: true }}
+      domLayout="autoHeight"
+    />
+  );
+}
+
+export default BooleanFilterExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <Table
+        rowData={BOOLEAN_FILTER_IN_TABLE_DATA}
+        columnDefs={[
+          { field: 'name', headerName: 'Name', flex: 2 },
+          {
+            field: 'active',
+            headerName: 'Active',
+            flex: 1,
+            editable: false,
+            cellRenderer: 'dsBooleanCellRenderer',
+            filter: { component: BooleanFilter, doesFilterPass: doesBooleanFilterPass },
+            suppressHeaderFilterButton: false,
+          },
+        ]}
+        defaultColDef={{ flex: 1, minWidth: 120, suppressHeaderFilterButton: true }}
+        domLayout="autoHeight"
+      />
+    ),
+  },
+  '`BooleanFilter` wired up inside a full `Table`. Click the funnel icon in the **Active** column header to open the filter panel — select **Yes**, **No**, or **Not set** to filter the rows. The Active column also uses `dsBooleanCellRenderer` to show check/✕ icons.',
+);

package/src/components/table/columnFilters/TimeFilter.stories.tsx

@@ -0,0 +1,281 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import {
+  Controls,
+  Heading as DocHeading,
+  Markdown,
+  Primary as DocPrimary,
+  Stories,
+  Subtitle,
+  Title,
+} from '@storybook/addon-docs/blocks';
+import { fn } from 'storybook/test';
+import { TimeFilter, doesTimeFilterPass } from './TimeFilter/TimeFilter';
+import { Table } from 'Components/table/Table';
+
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = [
+  '`TimeFilter` is an AG Grid column filter component for time-string columns.',
+  'It renders a filter-type selector (**Before**, **After**, **At**) and a time input,',
+  'then calls `onModelChange` with a `{ filterType, pivot }` model when either changes.',
+  '',
+  'Register it via the AG Grid `filter` column definition property alongside `doesTimeFilterPass`.',
+].join('\n');
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- On columns containing time strings (e.g. `"09:30"`, `"14:45"`) that need a time-based filter',
+  '- When users need to find rows before, after, or at a specific time',
+  '',
+  '---',
+  '',
+  '### Registration',
+  '',
+  '```tsx',
+  "import { TimeFilter, doesTimeFilterPass } from '@arbor-education/design-system.components';",
+  '',
+  'const colDefs = [',
+  '  {',
+  "    field: 'startTime',",
+  '    filter: { component: TimeFilter, doesFilterPass: doesTimeFilterPass },',
+  '  },',
+  '];',
+  '```',
+  '',
+  '---',
+  '',
+  '### Filter model',
+  '',
+  '```ts',
+  'type TimeFilterModel = {',
+  "  filterType: 'before' | 'after' | 'equal';",
+  '  pivot: string; // HH:mm format, e.g. "09:30"',
+  '};',
+  '```',
+  '',
+  '---',
+  '',
+  '### `doesTimeFilterPass`',
+  '',
+  '`doesTimeFilterPass` is the companion filter function. Import it alongside `TimeFilter` and pass',
+  'it to `doesFilterPass` in your column definition. It compares the cell value (time string or `Date`)',
+  'against the `pivot` using the selected `filterType`.',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[Table](?path=/docs/components-table--docs) · [BooleanFilter](?path=/docs/components-table-columnfilters-booleanfilter--docs)',
+].join('\n');
+
+const PROPS_INTRO = 'The preview below is interactive — change the filter type or time value to see the model update in the **Actions** panel.';
+
+// ---------------------------------------------------------------------------
+// Custom DocsPage
+// ---------------------------------------------------------------------------
+
+function TimeFilterDocsPage() {
+  return (
+    <>
+      <Title />
+      <Subtitle />
+      <Markdown>{DESCRIPTION_INTRO}</Markdown>
+      <DocHeading>Interactive example</DocHeading>
+      <Markdown>{PROPS_INTRO}</Markdown>
+      <DocPrimary />
+      <Controls />
+      <DocHeading>Usage guidance</DocHeading>
+      <Markdown>{USAGE_GUIDANCE}</Markdown>
+      <DocHeading>Examples</DocHeading>
+      <Stories title="" />
+      <Markdown>{RELATED_COMPONENTS}</Markdown>
+    </>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Meta
+// ---------------------------------------------------------------------------
+
+const meta = {
+  title: 'Components/Table/ColumnFilters/TimeFilter',
+  component: TimeFilter,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: { page: TimeFilterDocsPage },
+  },
+  argTypes: {
+    model: {
+      description: 'The current filter model. `null` means no filter is active. Provide `{ filterType, pivot }` to pre-set the filter.',
+      control: false,
+      table: { type: { summary: '{ filterType: "before" | "after" | "equal"; pivot: string } | null' }, defaultValue: { summary: 'null' } },
+    },
+    onModelChange: {
+      description: 'Called whenever the user changes the filter type or time value. Receives the new `{ filterType, pivot }` model.',
+      control: false,
+      table: { type: { summary: '(model: TimeFilterModel) => void' } },
+    },
+  },
+  args: {
+    onModelChange: fn(),
+  },
+} satisfies Meta<typeof TimeFilter>;
+
+export default meta;
+type Story = StoryObj<typeof TimeFilter>;
+
+const withDescription = (story: Story, description: string): Story => ({
+  ...story,
+  parameters: {
+    ...story.parameters,
+    docs: { ...story.parameters?.docs, description: { story: description } },
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+export const Default: Story = withDescription(
+  {
+    args: {
+      model: null,
+      onModelChange: fn(),
+    },
+  },
+  'No active filter (`model: null`) — filter type defaults to **Before**, time input is empty.',
+);
+
+export const BeforeNoon: Story = withDescription(
+  {
+    parameters: { controls: { disable: true } },
+    args: {
+      model: { filterType: 'before', pivot: '12:00' },
+      onModelChange: fn(),
+    },
+  },
+  '**Before 12:00** — shows rows where the cell value is a time before noon.',
+);
+
+export const AfterNine: Story = withDescription(
+  {
+    parameters: { controls: { disable: true } },
+    args: {
+      model: { filterType: 'after', pivot: '09:00' },
+      onModelChange: fn(),
+    },
+  },
+  '**After 09:00** — shows rows where the cell value is a time after 9am.',
+);
+
+export const ExactTime: Story = withDescription(
+  {
+    parameters: { controls: { disable: true } },
+    args: {
+      model: { filterType: 'equal', pivot: '14:30' },
+      onModelChange: fn(),
+    },
+  },
+  '**At 14:30** — shows rows where the cell value exactly matches the pivot time.',
+);
+
+export const Controlled: Story = withDescription(
+  {
+    parameters: { controls: { disable: true } },
+    render: () => {
+      const [model, setModel] = React.useState<{ filterType: 'before' | 'after' | 'equal'; pivot: string } | null>(null);
+      return (
+        <div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>
+          <TimeFilter model={model} onModelChange={setModel} />
+          <pre style={{ fontSize: '12px', background: 'var(--color-neutral-50)', padding: '8px', borderRadius: '4px' }}>
+            {model ? JSON.stringify(model, null, 2) : 'null'}
+          </pre>
+        </div>
+      );
+    },
+  },
+  'Fully controlled — the current model is rendered below the filter as JSON. Interact with the filter to see the model update in real time.',
+);
+
+const TIME_FILTER_IN_TABLE_DATA = [
+  { pupil: 'Alice Johnson', registrationTime: '08:45' },
+  { pupil: 'Bob Smith', registrationTime: '09:15' },
+  { pupil: 'Charlie Brown', registrationTime: '09:00' },
+  { pupil: 'Diana Prince', registrationTime: '10:30' },
+  { pupil: 'Ethan Hunt', registrationTime: '08:30' },
+];
+
+export const InATable: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import {
+  Table,
+  TimeFilter,
+  doesTimeFilterPass,
+} from '@arbor-education/design-system.components';
+
+const rowData = [
+  { pupil: 'Alice Johnson', registrationTime: '08:45' },
+  { pupil: 'Bob Smith', registrationTime: '09:15' },
+  { pupil: 'Charlie Brown', registrationTime: '09:00' },
+  { pupil: 'Diana Prince', registrationTime: '10:30' },
+  { pupil: 'Ethan Hunt', registrationTime: '08:30' },
+];
+
+function TimeFilterExample() {
+  return (
+    <Table
+      rowData={rowData}
+      columnDefs={[
+        { field: 'pupil', headerName: 'Pupil', flex: 2 },
+        {
+          field: 'registrationTime',
+          headerName: 'Registration time',
+          flex: 1,
+          editable: false,
+          filter: { component: TimeFilter, doesFilterPass: doesTimeFilterPass },
+          suppressHeaderFilterButton: false,
+        },
+      ]}
+      defaultColDef={{ flex: 1, minWidth: 120, suppressHeaderFilterButton: true }}
+      domLayout="autoHeight"
+    />
+  );
+}
+
+export default TimeFilterExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <Table
+        rowData={TIME_FILTER_IN_TABLE_DATA}
+        columnDefs={[
+          { field: 'pupil', headerName: 'Pupil', flex: 2 },
+          {
+            field: 'registrationTime',
+            headerName: 'Registration time',
+            flex: 1,
+            editable: false,
+            filter: { component: TimeFilter, doesFilterPass: doesTimeFilterPass },
+            suppressHeaderFilterButton: false,
+          },
+        ]}
+        defaultColDef={{ flex: 1, minWidth: 120, suppressHeaderFilterButton: true }}
+        domLayout="autoHeight"
+      />
+    ),
+  },
+  '`TimeFilter` wired up inside a full `Table`. Click the funnel icon in the **Registration time** column header to open the filter panel — choose **Before**, **After**, or **At** and enter a time (e.g. `09:00`) to filter the rows.',
+);