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

package/src/components/arborLogo/ArborLogo.stories.tsx

@@ -0,0 +1,663 @@
+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 { ArborLogo } from './ArborLogo';
+
+const DESCRIPTION_INTRO = `
+ArborLogo renders the Arbor Education brand mark as an inline SVG with a built-in \`<title>\` element for accessibility.
+
+Reach for it whenever the Arbor identity needs to appear on screen — application headers, login and splash screens, homepage links, email and report headers, and any dark hero panel that calls for the white wordmark variant.
+`.trim();
+
+const USAGE_GUIDANCE = `
+### When to use
+
+- **Application headers** — the icon-only mark fits compact top-nav bars and rails where horizontal space is precious.
+- **Login, onboarding, and splash screens** — the full wordmark establishes brand context the moment a user lands.
+- **Homepage links** — wrap the logo in an anchor and pass \`aria-label="Arbor home"\` so assistive tech announces the destination clearly.
+- **Email and report headers** — the dark wordmark on a light background is the canonical lockup for printed and emailed artefacts.
+- **Dark hero panels and sidebars** — switch to \`textColor="white"\` so the wordmark stays legible.
+
+---
+
+### When NOT to use
+
+| Scenario | Use instead |
+|---|---|
+| Generic decorative iconography | [\`Icon\`](?path=/docs/components-icon--docs) |
+| Arbitrary image asset | A plain \`<img>\` with the hosted asset URL |
+| A school's crest or logo | A separate, school-supplied image — ArborLogo is the *Arbor Education* mark only |
+| Repeating decorative flourish where any abstract shape would do | Don't dilute the brand — pick a neutral shape or pattern instead |
+`.trim();
+
+const DEVELOPER_NOTES = `
+### Critical usage patterns
+
+**\`textColor\` is silently ignored when \`showText\` is falsy.** The icon-only mark uses fixed brand colours that cannot be customised — \`textColor\` only affects the wordmark.
+
+**\`aria-label\` becomes the \`<title>\` text, not an \`aria-label\` attribute.** If you inspect the DOM you'll find \`aria-labelledby="..."\` pointing to a \`<title>\` element, not \`aria-label="..."\` on the SVG itself. The two are functionally equivalent for screen readers but visually different in DevTools.
+
+**\`aria-hidden\` strips ALL accessibility attributes.** When set, the SVG drops \`role\`, \`aria-labelledby\`, and the inner \`<title>\` element entirely — and any \`aria-label\` you pass is silently ignored. Don't combine the two.
+
+**The "black" wordmark is \`#2F2F2F\`, not pure black.** That's a brand decision, equivalent to \`--color-grey-900\`. If a designer asks why it isn't \`#000\`, that's the answer.
+
+**SVG dimensions are hardcoded.** The icon-only variant is 25×25 px and the full logo is 66×26 px. To resize, apply CSS via \`className\` (for example \`width: 120px; height: auto\`). Setting width without \`height: auto\` distorts the aspect ratio. There are no \`width\` or \`height\` props.
+
+**Multiple ArborLogos on one page won't clash.** Internal \`<clipPath>\` and \`<title>\` IDs are generated with React's \`useId()\`, so duplicate instances stay isolated.
+
+---
+
+### Accessibility
+
+- By default the SVG has \`role="img"\` and the inner \`<title>\` provides the accessible name (\`"Arbor"\` unless overridden).
+- For brand context override, pass \`aria-label\` — for example \`aria-label="Arbor home"\` when the logo links to the homepage.
+- For decorative use alongside visible "Arbor" text, pass \`aria-hidden\` so screen readers don't announce the brand twice.
+- Never combine \`aria-label\` and \`aria-hidden\` — \`aria-label\` is ignored when the SVG is hidden.
+
+---
+
+### TypeScript types
+
+\`\`\`ts
+import type { ArborLogoProps } from '@arbor-education/design-system.components';
+\`\`\`
+
+| Prop | Type | Default |
+|---|---|---|
+| \`showText\` | \`boolean\` | \`undefined\` (icon-only) |
+| \`textColor\` | \`'white' \\| 'black'\` | \`'black'\` |
+| \`aria-label\` | \`string\` | \`'Arbor'\` |
+| \`aria-hidden\` | \`boolean\` | \`undefined\` |
+| \`className\` | \`string\` | \`undefined\` |
+`.trim();
+
+const RELATED_COMPONENTS = `
+## Related components
+
+[Icon](?path=/docs/components-icon--docs)
+`.trim();
+
+const PROPS_INTRO
+  = 'The preview below is wired to the **Controls** panel — tweak any prop to see the story update in real time.';
+
+function ArborLogoDocsPage() {
+  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>Developer notes</DocHeading>
+      <Markdown>{DEVELOPER_NOTES}</Markdown>
+      <DocHeading>Examples</DocHeading>
+      <Stories title="" />
+      <Markdown>{RELATED_COMPONENTS}</Markdown>
+    </>
+  );
+}
+
+const meta = {
+  title: 'Components/ArborLogo',
+  component: ArborLogo,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      page: ArborLogoDocsPage,
+    },
+  },
+  argTypes: {
+    'showText': {
+      description:
+        'When true, renders the full 66×26 px logo with wordmark. When falsy, renders the 25×25 px icon-only mark.',
+      control: { type: 'boolean' },
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    'textColor': {
+      description:
+        'Wordmark colour. Only takes effect when `showText` is true. The "black" value renders as `#2F2F2F` (equivalent to `--color-grey-900`).',
+      control: { type: 'radio' },
+      options: ['white', 'black'],
+      table: {
+        type: { summary: '\'white\' | \'black\'' },
+        defaultValue: { summary: '\'black\'' },
+      },
+    },
+    'aria-label': {
+      description:
+        'Accessible name. Rendered as the SVG\'s inner `<title>` text and referenced via `aria-labelledby`. Ignored when `aria-hidden` is set.',
+      control: { type: 'text' },
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: '\'Arbor\'' },
+      },
+    },
+    'aria-hidden': {
+      description:
+        'When truthy, marks the SVG as decorative — strips `role`, `aria-labelledby`, and the inner `<title>`. Use when adjacent visible text already conveys the brand name.',
+      control: { type: 'boolean' },
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    'className': {
+      description:
+        'Class applied to the root SVG. Use this to resize via CSS (for example `width: 120px; height: auto`) — there are no width/height props.',
+      control: { type: 'text' },
+      table: {
+        type: { summary: 'string' },
+      },
+    },
+  },
+} satisfies Meta<typeof ArborLogo>;
+
+export default meta;
+
+// Use StoryObj<typeof ArborLogo> (not typeof meta) so render-only stories are
+// not forced to provide every required arg — template components handle their own instances.
+type Story = StoryObj<typeof ArborLogo>;
+
+const withDescription = (story: Story, description: string): Story => ({
+  ...story,
+  parameters: {
+    ...story.parameters,
+    docs: {
+      ...story.parameters?.docs,
+      description: {
+        story: description,
+      },
+    },
+  },
+});
+
+export const Default: Story = withDescription(
+  {
+    args: {
+      'showText': true,
+      'textColor': 'black',
+      'aria-label': 'Arbor',
+      'aria-hidden': false,
+    },
+    decorators: [
+      (StoryFn, context) => {
+        const isDark = context.args.textColor === 'white';
+        return (
+          <div
+            style={{
+              alignItems: 'center',
+              backgroundColor: isDark
+                ? 'var(--color-grey-800)'
+                : 'var(--color-grey-050)',
+              borderRadius: 'var(--border-radius-xsmall)',
+              display: 'flex',
+              justifyContent: 'center',
+              padding: 'var(--spacing-xlarge)',
+            }}
+          >
+            <StoryFn />
+          </div>
+        );
+      },
+    ],
+    render: args => <ArborLogo {...args} />,
+  },
+  'Interactive playground. Toggle `showText` to switch between the icon-only mark and the full wordmark, then flip `textColor` — the wrapper background swaps automatically so the white variant stays visible.',
+);
+
+export const IconOnly: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { ArborLogo } from '@arbor-education/design-system.components';
+
+function ArborLogoIconOnlyExample() {
+  return <ArborLogo aria-label="Arbor" />;
+}
+export default ArborLogoIconOnlyExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div
+        style={{
+          alignItems: 'center',
+          backgroundColor: 'var(--color-grey-050)',
+          borderRadius: 'var(--border-radius-xsmall)',
+          display: 'flex',
+          justifyContent: 'center',
+          padding: 'var(--spacing-xlarge)',
+        }}
+      >
+        <ArborLogo aria-label="Arbor" />
+      </div>
+    ),
+  },
+  'The 25×25 px icon-only mark. Reach for this in compact spaces — top-nav rails, app icons, favourited shortcuts — where the wordmark would crowd the layout.',
+);
+
+export const WithWordmark: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { ArborLogo } from '@arbor-education/design-system.components';
+
+function ArborLogoWithWordmarkExample() {
+  return <ArborLogo showText aria-label="Arbor" />;
+}
+export default ArborLogoWithWordmarkExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div
+        style={{
+          alignItems: 'center',
+          backgroundColor: 'var(--color-grey-050)',
+          borderRadius: 'var(--border-radius-xsmall)',
+          display: 'flex',
+          justifyContent: 'center',
+          padding: 'var(--spacing-xlarge)',
+        }}
+      >
+        <ArborLogo showText aria-label="Arbor" />
+      </div>
+    ),
+  },
+  'The canonical brand lockup — full 66×26 px logo with the dark `#2F2F2F` wordmark on a light surface. Use this for login screens, email headers, and printed reports.',
+);
+
+const WhiteWordmarkTemplate = () => (
+  <div
+    style={{
+      display: 'flex',
+      flexDirection: 'column',
+      gap: 'var(--spacing-large)',
+    }}
+  >
+    <div
+      style={{
+        alignItems: 'center',
+        backgroundColor: 'var(--color-grey-800)',
+        borderRadius: 'var(--border-radius-xsmall)',
+        display: 'flex',
+        justifyContent: 'center',
+        padding: 'var(--spacing-xlarge)',
+      }}
+    >
+      <ArborLogo showText textColor="white" aria-label="Arbor" />
+    </div>
+    <span
+      className="ds-text"
+      style={{
+        color: 'var(--color-grey-600)',
+        fontStyle: 'italic',
+      }}
+    >
+      The dark background is part of the story, not the component — pair the
+      white wordmark with a sufficiently dark surface in your own layout.
+    </span>
+  </div>
+);
+
+export const WhiteWordmark: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { ArborLogo } from '@arbor-education/design-system.components';
+
+function ArborLogoWhiteWordmarkExample() {
+  return (
+    <div style={{ background: 'var(--color-grey-800)', padding: 'var(--spacing-xlarge)', display: 'inline-flex' }}>
+      <ArborLogo showText textColor="white" aria-label="Arbor" />
+    </div>
+  );
+}
+export default ArborLogoWhiteWordmarkExample;
+`.trim(),
+        },
+      },
+    },
+    render: WhiteWordmarkTemplate,
+  },
+  'Switch the wordmark to white for dark hero panels, marketing splash screens, and inverted sidebars. The component itself does nothing to the surrounding background — that is the consumer\'s responsibility.',
+);
+
+const DecorativeTemplate = () => (
+  <div
+    style={{
+      display: 'flex',
+      flexDirection: 'column',
+      gap: 'var(--spacing-xxlarge)',
+    }}
+  >
+    <div
+      style={{
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 'var(--spacing-large)',
+      }}
+    >
+      <div
+        style={{
+          alignItems: 'center',
+          backgroundColor: 'var(--color-grey-050)',
+          borderRadius: 'var(--border-radius-xsmall)',
+          display: 'flex',
+          gap: 'var(--spacing-small)',
+          padding: 'var(--spacing-xlarge)',
+        }}
+      >
+        <ArborLogo aria-hidden />
+        <span className="ds-text">Arbor</span>
+      </div>
+      <span
+        className="ds-text"
+        style={{
+          color: 'var(--color-grey-600)',
+          fontStyle: 'italic',
+        }}
+      >
+        Screen reader announces:
+        {' '}
+        <strong>&ldquo;Arbor&rdquo;</strong>
+        {' '}
+        — once, from the visible text.
+      </span>
+    </div>
+
+    <div
+      style={{
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 'var(--spacing-large)',
+      }}
+    >
+      <div
+        style={{
+          alignItems: 'center',
+          backgroundColor: 'var(--color-grey-050)',
+          borderRadius: 'var(--border-radius-xsmall)',
+          display: 'flex',
+          gap: 'var(--spacing-small)',
+          padding: 'var(--spacing-xlarge)',
+        }}
+      >
+        <ArborLogo showText aria-hidden />
+        <span className="ds-text">— Dashboard</span>
+      </div>
+      <span
+        className="ds-text"
+        style={{
+          color: 'var(--color-grey-600)',
+          fontStyle: 'italic',
+        }}
+      >
+        Screen reader announces:
+        {' '}
+        <strong>&ldquo;— Dashboard&rdquo;</strong>
+        {' '}
+        — the logo is skipped because the wordmark is already visible.
+      </span>
+    </div>
+  </div>
+);
+
+export const Decorative: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { ArborLogo } from '@arbor-education/design-system.components';
+
+function ArborLogoDecorativeExample() {
+  return (
+    <header style={{ display: 'flex', alignItems: 'center', gap: 'var(--spacing-small)' }}>
+      <ArborLogo aria-hidden />
+      <span>Arbor</span>
+    </header>
+  );
+}
+export default ArborLogoDecorativeExample;
+`.trim(),
+        },
+      },
+    },
+    render: DecorativeTemplate,
+  },
+  'Use `aria-hidden` whenever an adjacent visible "Arbor" wordmark already announces the brand — repeating it via the SVG just doubles the screen-reader output. Both examples below show the same content with the logo correctly hidden from assistive tech.',
+);
+
+const CustomAccessibleNameTemplate = () => (
+  <div
+    style={{
+      display: 'flex',
+      flexDirection: 'column',
+      gap: 'var(--spacing-large)',
+    }}
+  >
+    <div
+      style={{
+        alignItems: 'center',
+        backgroundColor: 'var(--color-grey-050)',
+        borderRadius: 'var(--border-radius-xsmall)',
+        display: 'flex',
+        justifyContent: 'center',
+        padding: 'var(--spacing-xlarge)',
+      }}
+    >
+      <a
+        href="/"
+        style={{
+          alignItems: 'center',
+          display: 'inline-flex',
+          padding: 'var(--spacing-small)',
+          textDecoration: 'none',
+        }}
+      >
+        <ArborLogo showText aria-label="Arbor home" />
+      </a>
+    </div>
+    <span
+      className="ds-text"
+      style={{
+        color: 'var(--color-grey-600)',
+        fontStyle: 'italic',
+      }}
+    >
+      Screen reader announces:
+      {' '}
+      <strong>&ldquo;Arbor home, link&rdquo;</strong>
+      {' '}
+      — the accessible name clarifies that the brand mark is also the homepage destination.
+    </span>
+  </div>
+);
+
+export const CustomAccessibleName: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { ArborLogo } from '@arbor-education/design-system.components';
+
+function ArborLogoCustomAccessibleNameExample() {
+  return (
+    <a href="/">
+      <ArborLogo showText aria-label="Arbor home" />
+    </a>
+  );
+}
+export default ArborLogoCustomAccessibleNameExample;
+`.trim(),
+        },
+      },
+    },
+    render: CustomAccessibleNameTemplate,
+  },
+  'When the logo is the homepage link, override `aria-label` so screen-reader users hear the destination, not just the brand name. The default `"Arbor"` label is fine for purely decorative brand placement, but link targets deserve more context.',
+);
+
+// Inline <style> tags inside the template inject the CSS rules referenced by
+// the className examples below. In a real app these rules would live in your
+// stylesheet — Storybook can't resize the SVG without them because width/height
+// are baked into the SVG attributes.
+const CustomSizingTemplate = () => (
+  <>
+    <style>
+      {`
+        .my-arbor-logo--favicon { width: 16px; height: auto; }
+        .my-arbor-logo--hero { width: 240px; height: auto; }
+      `}
+    </style>
+    <div
+      style={{
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 'var(--spacing-large)',
+      }}
+    >
+      <div
+        style={{
+          alignItems: 'flex-end',
+          backgroundColor: 'var(--color-grey-050)',
+          borderRadius: 'var(--border-radius-xsmall)',
+          display: 'flex',
+          gap: 'var(--spacing-xxlarge)',
+          justifyContent: 'center',
+          padding: 'var(--spacing-xlarge)',
+        }}
+      >
+        <div
+          style={{
+            alignItems: 'center',
+            display: 'flex',
+            flexDirection: 'column',
+            gap: 'var(--spacing-small)',
+          }}
+        >
+          <ArborLogo showText aria-label="Arbor" className="my-arbor-logo--favicon" />
+          <span
+            className="ds-text"
+            style={{ color: 'var(--color-grey-600)' }}
+          >
+            16 px (favicon)
+          </span>
+        </div>
+        <div
+          style={{
+            alignItems: 'center',
+            display: 'flex',
+            flexDirection: 'column',
+            gap: 'var(--spacing-small)',
+          }}
+        >
+          <ArborLogo showText aria-label="Arbor" />
+          <span
+            className="ds-text"
+            style={{ color: 'var(--color-grey-600)' }}
+          >
+            66 px (default)
+          </span>
+        </div>
+        <div
+          style={{
+            alignItems: 'center',
+            display: 'flex',
+            flexDirection: 'column',
+            gap: 'var(--spacing-small)',
+          }}
+        >
+          <ArborLogo showText aria-label="Arbor" className="my-arbor-logo--hero" />
+          <span
+            className="ds-text"
+            style={{ color: 'var(--color-grey-600)' }}
+          >
+            240 px (hero / login)
+          </span>
+        </div>
+      </div>
+      <span
+        className="ds-text"
+        style={{
+          color: 'var(--color-grey-600)',
+          fontStyle: 'italic',
+        }}
+      >
+        Resizing happens via CSS in your own stylesheet — for example
+        {' '}
+        <code>.my-arbor-logo--hero &#123; width: 240px; height: auto; &#125;</code>
+        . Always set
+        {' '}
+        <code>height: auto</code>
+        {' '}
+        alongside
+        {' '}
+        <code>width</code>
+        {' '}
+        to preserve the 66:26 aspect ratio.
+      </span>
+    </div>
+  </>
+);
+
+export const CustomSizing: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { ArborLogo } from '@arbor-education/design-system.components';
+
+// In your stylesheet:
+//   .my-arbor-logo--hero { width: 240px; height: auto; }
+
+function ArborLogoCustomSizingExample() {
+  return <ArborLogo showText aria-label="Arbor" className="my-arbor-logo--hero" />;
+}
+export default ArborLogoCustomSizingExample;
+`.trim(),
+        },
+      },
+    },
+    render: CustomSizingTemplate,
+  },
+  'SVG width and height are baked into the component — to resize, target the SVG with CSS via `className`. Always pair `width` with `height: auto` to preserve the 66:26 aspect ratio. The three sizes shown here cover the realistic range: favicon, default, and login hero.',
+);

package/src/components/arborLogo/ArborLogo.test.tsx

@@ -0,0 +1,36 @@
+import { expect, describe, it } from 'vitest';
+import { render } from '@testing-library/react';
+import '@testing-library/jest-dom/vitest';
+import { ArborLogo } from './ArborLogo';
+
+describe('ArborLogo', () => {
+  it('renders the icon-only variant', () => {
+    const { container } = render(<ArborLogo />);
+    expect(container.firstChild).toMatchSnapshot();
+  });
+
+  it('renders the icon-only variant with aria-hidden', () => {
+    const { container } = render(<ArborLogo aria-hidden />);
+    expect(container.firstChild).toMatchSnapshot();
+  });
+
+  it('renders the icon-only variant with a custom aria-label', () => {
+    const { container } = render(<ArborLogo aria-label="Arbor Education logo" />);
+    expect(container.firstChild).toMatchSnapshot();
+  });
+
+  it('renders the text variant with black text', () => {
+    const { container } = render(<ArborLogo showText />);
+    expect(container.firstChild).toMatchSnapshot();
+  });
+
+  it('renders the text variant with white text', () => {
+    const { container } = render(<ArborLogo showText textColor="white" />);
+    expect(container.firstChild).toMatchSnapshot();
+  });
+
+  it('renders the text variant with aria-hidden', () => {
+    const { container } = render(<ArborLogo showText aria-hidden />);
+    expect(container.firstChild).toMatchSnapshot();
+  });
+});