@forumone/create-throughline 0.2.0 → 0.3.0

package/dist/templates/with-reference-ds/design-system/src/components/CardGrid/CardGrid.contract.ts

@@ -0,0 +1,78 @@
+import type { ComponentContract } from '@forumone/throughline-design-contract'
+
+export const contract: ComponentContract = {
+  name: 'CardGrid',
+  category: 'section',
+  description:
+    'A responsive layout container for two, three, or four Cards per row. Reflows to fewer columns on narrow viewports.',
+  intent:
+    'Lay out multiple Card components inside a section. Use for program lists, blog indexes, staff directories, and any collection of similarly-shaped content. CardGrid is purely layout; it does not fetch data or filter — authors list the Cards they want.',
+
+  composition: {
+    placement: ['section'],
+    maxPerPage: null,
+    requiredSiblings: ['Card'],
+    forbiddenAdjacent: [],
+    allowedSlots: { children: ['Card'] },
+  },
+
+  content: {
+    fields: [
+      {
+        name: 'children',
+        type: 'array',
+        required: true,
+        constraints: 'An array of Card components',
+        of: [{ name: 'card', type: 'group', required: true }],
+      },
+    ],
+    variants: [
+      { name: '2', description: 'Two columns', whenToUse: 'Lists of 2-4 prominent items' },
+      { name: '3', description: 'Three columns', whenToUse: 'Default — works for most collections' },
+      { name: '4', description: 'Four columns', whenToUse: 'Denser lists of 8 or more short cards' },
+    ],
+  },
+
+  tokens: {
+    consumes: ['spacing.container', 'spacing.6'],
+    configurable: [
+      { prop: 'columns', tokenGroup: 'layout', allowedValues: ['2', '3', '4'] },
+    ],
+  },
+
+  accessibility: {
+    keyboardSupport: [],
+    screenReaderBehavior:
+      'Purely visual layout. Screen readers traverse children in source order; CardGrid itself adds no ARIA.',
+    contentWarnings: [
+      'Children must be Cards; mixing other components breaks the visual rhythm',
+      'Keep all cards roughly the same content length — dramatically unequal cards look broken',
+    ],
+  },
+
+  examples: [
+    { label: 'Two columns', intent: 'Featured program pair', storyId: 'card-grid--two-column' },
+    { label: 'Three columns', intent: 'Standard content index', storyId: 'card-grid--three-column' },
+    { label: 'Four columns', intent: 'Dense staff directory', storyId: 'card-grid--four-column' },
+  ],
+
+  antiExamples: [
+    {
+      label: 'Mixing Cards and non-Card children',
+      why: 'The grid assumes uniform children; mixing Stats or MediaBlocks produces broken columns',
+      useInstead: 'Group by type — one CardGrid, then the other components below',
+    },
+    {
+      label: 'Using CardGrid with a single Card',
+      why: 'A CardGrid wrapping one Card is overhead without benefit',
+      useInstead: 'Render the Card directly',
+    },
+  ],
+
+  behavior: {
+    fetchesData: false,
+    hasClientState: false,
+    animates: false,
+    requiresAnalytics: false,
+  },
+}

package/dist/templates/with-reference-ds/design-system/src/components/CardGrid/CardGrid.module.css

@@ -0,0 +1,34 @@
+.grid {
+  max-width: 72rem;
+  margin: 0 auto;
+  padding: 0 var(--spacing-container);
+  display: grid;
+  gap: var(--spacing-6);
+}
+
+.cols-2 {
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+}
+
+.cols-3 {
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+}
+
+.cols-4 {
+  grid-template-columns: repeat(4, minmax(0, 1fr));
+}
+
+@media (max-width: 960px) {
+  .cols-3,
+  .cols-4 {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+}
+
+@media (max-width: 600px) {
+  .cols-2,
+  .cols-3,
+  .cols-4 {
+    grid-template-columns: 1fr;
+  }
+}

package/dist/templates/with-reference-ds/design-system/src/components/CardGrid/CardGrid.stories.tsx

@@ -0,0 +1,36 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { Card } from '../Card/Card.js'
+import { CardGrid } from './CardGrid.js'
+
+const meta: Meta<typeof CardGrid> = {
+  title: 'Card Grid',
+  component: CardGrid,
+}
+
+export default meta
+
+type Story = StoryObj<typeof CardGrid>
+
+function sampleCards(count: number) {
+  return Array.from({ length: count }, (_, index) => (
+    <Card
+      key={index}
+      image={{ url: `https://placehold.co/640x360?text=${index + 1}`, alt: `Placeholder ${index + 1}` }}
+      title={`Program ${index + 1}`}
+      description="Short description of this program or piece of content."
+      link={{ label: 'Learn more', url: '#' }}
+    />
+  ))
+}
+
+export const TwoColumn: Story = {
+  args: { columns: 2, children: sampleCards(4) },
+}
+
+export const ThreeColumn: Story = {
+  args: { columns: 3, children: sampleCards(6) },
+}
+
+export const FourColumn: Story = {
+  args: { columns: 4, children: sampleCards(8) },
+}

package/dist/templates/with-reference-ds/design-system/src/components/CardGrid/CardGrid.test.tsx

@@ -0,0 +1,25 @@
+import { render, screen } from '@testing-library/react'
+import { describe, expect, it } from 'vitest'
+import { CardGrid } from './CardGrid.js'
+
+describe('CardGrid', () => {
+  it('renders children', () => {
+    render(
+      <CardGrid>
+        <div data-testid="a">A</div>
+        <div data-testid="b">B</div>
+      </CardGrid>,
+    )
+    expect(screen.getByTestId('a')).toBeInTheDocument()
+    expect(screen.getByTestId('b')).toBeInTheDocument()
+  })
+
+  it('applies the columns modifier class', () => {
+    const { container } = render(
+      <CardGrid columns={4}>
+        <div />
+      </CardGrid>,
+    )
+    expect((container.firstChild as HTMLElement).className).toContain('cols-4')
+  })
+})

package/dist/templates/with-reference-ds/design-system/src/components/CardGrid/CardGrid.tsx

@@ -0,0 +1,19 @@
+import { clsx } from 'clsx'
+import type { ReactNode } from 'react'
+import styles from './CardGrid.module.css'
+
+export type CardGridColumns = 2 | 3 | 4
+
+export interface CardGridProps {
+  children: ReactNode
+  columns?: CardGridColumns
+  className?: string
+}
+
+export function CardGrid({ children, columns = 3, className }: CardGridProps) {
+  return (
+    <div className={clsx(styles.grid, styles[`cols-${columns}`], className)}>
+      {children}
+    </div>
+  )
+}

package/dist/templates/with-reference-ds/design-system/src/components/CardGrid/index.ts

@@ -0,0 +1,2 @@
+export { CardGrid, type CardGridProps, type CardGridColumns } from './CardGrid.js'
+export { contract as cardGridContract } from './CardGrid.contract.js'

package/dist/templates/with-reference-ds/design-system/src/components/Divider/Divider.contract.ts

@@ -0,0 +1,87 @@
+import type { ComponentContract } from '@forumone/throughline-design-contract'
+
+export const contract: ComponentContract = {
+  name: 'Divider',
+  category: 'utility',
+  description: 'A horizontal rule for separating sections of content.',
+  intent:
+    'Mark a visual pause between two blocks of content without introducing a new section header. Use sparingly — a SectionIntro is usually a better signal of a new topic. Divider is for rhythm, not hierarchy.',
+
+  composition: {
+    placement: ['page', 'section', 'inline'],
+    maxPerPage: null,
+    requiredSiblings: [],
+    forbiddenAdjacent: ['Divider'],
+  },
+
+  content: {
+    fields: [
+      {
+        name: 'spacing',
+        type: 'select',
+        required: false,
+        constraints: 'compact | default | spacious',
+      },
+      {
+        name: 'decorative',
+        type: 'boolean',
+        required: false,
+        constraints: 'When true (default), the divider is aria-hidden',
+      },
+    ],
+    variants: [
+      { name: 'compact', description: 'Small vertical margin', whenToUse: 'Between tight pieces of content inside a list' },
+      { name: 'default', description: 'Standard vertical margin', whenToUse: 'Most cases' },
+      { name: 'spacious', description: 'Large vertical margin', whenToUse: 'Between major sections of a page' },
+    ],
+  },
+
+  tokens: {
+    consumes: [
+      'color.border.default',
+      'spacing.24',
+      'spacing.12',
+      'spacing.6',
+    ],
+    configurable: [
+      { prop: 'spacing', tokenGroup: 'spacing', allowedValues: ['compact', 'default', 'spacious'] },
+    ],
+  },
+
+  accessibility: {
+    role: 'separator',
+    keyboardSupport: [],
+    screenReaderBehavior:
+      'When decorative=true (default) the divider is marked aria-hidden and assistive tech skips it. When decorative=false it announces as a separator.',
+    contentWarnings: [
+      'Do not stack two Dividers in a row',
+    ],
+  },
+
+  examples: [
+    { label: 'Default', intent: 'Standard section break', storyId: 'divider--default' },
+    { label: 'Compact', intent: 'Between related list items', storyId: 'divider--compact' },
+    { label: 'Spacious', intent: 'Between major page sections', storyId: 'divider--spacious' },
+    { label: 'Meaningful', intent: 'Semantic section break announced by screen readers', storyId: 'divider--meaningful' },
+  ],
+
+  antiExamples: [
+    {
+      label: 'Using Divider instead of SectionIntro',
+      why: 'Dividers carry no semantic meaning; readers cannot tell a new section has started without the accompanying headline',
+      useInstead: 'SectionIntro',
+    },
+    {
+      label: 'Decorative dividers announced to screen readers',
+      why: 'Adds noise without value',
+      useInstead: 'Leave decorative=true (the default)',
+    },
+  ],
+
+  behavior: {
+    fetchesData: false,
+    hasClientState: false,
+    animates: false,
+    requiresAnalytics: false,
+  },
+}

package/dist/templates/with-reference-ds/design-system/src/components/Divider/Divider.module.css

@@ -0,0 +1,18 @@
+.divider {
+  border: 0;
+  border-top: 1px solid var(--color-border-default);
+  max-width: 72rem;
+  margin-inline: auto;
+}
+
+.compact {
+  margin-block: var(--spacing-6);
+}
+
+.default {
+  margin-block: var(--spacing-12);
+}
+
+.spacious {
+  margin-block: var(--spacing-24);
+}

package/dist/templates/with-reference-ds/design-system/src/components/Divider/Divider.stories.tsx

@@ -0,0 +1,35 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { Divider } from './Divider.js'
+
+const meta: Meta<typeof Divider> = {
+  title: 'Divider',
+  component: Divider,
+}
+
+export default meta
+
+type Story = StoryObj<typeof Divider>
+
+export const Default: Story = {
+  render: (args) => (
+    <div>
+      <p>Above the divider.</p>
+      <Divider {...args} />
+      <p>Below the divider.</p>
+    </div>
+  ),
+}
+
+export const Compact: Story = { ...Default, args: { spacing: 'compact' } }
+export const Spacious: Story = { ...Default, args: { spacing: 'spacious' } }
+export const Meaningful: Story = {
+  ...Default,
+  args: { decorative: false },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Use decorative={false} when the divider marks a meaningful section break that assistive technology should announce.',
+      },
+    },
+  },
+}

package/dist/templates/with-reference-ds/design-system/src/components/Divider/Divider.test.tsx

@@ -0,0 +1,20 @@
+import { render } from '@testing-library/react'
+import { describe, expect, it } from 'vitest'
+import { Divider } from './Divider.js'
+
+describe('Divider', () => {
+  it('renders a hr element', () => {
+    const { container } = render(<Divider />)
+    expect(container.querySelector('hr')).not.toBeNull()
+  })
+
+  it('defaults to aria-hidden for decorative use', () => {
+    const { container } = render(<Divider />)
+    expect(container.querySelector('hr')).toHaveAttribute('aria-hidden', 'true')
+  })
+
+  it('removes aria-hidden when not decorative', () => {
+    const { container } = render(<Divider decorative={false} />)
+    expect(container.querySelector('hr')).not.toHaveAttribute('aria-hidden')
+  })
+})

package/dist/templates/with-reference-ds/design-system/src/components/Divider/Divider.tsx

@@ -0,0 +1,17 @@
+import { clsx } from 'clsx'
+import styles from './Divider.module.css'
+
+export type DividerSpacing = 'compact' | 'default' | 'spacious'
+
+export interface DividerProps {
+  spacing?: DividerSpacing
+  decorative?: boolean
+  className?: string
+}
+
+export function Divider({ spacing = 'default', decorative = true, className }: DividerProps) {
+  const ariaProps = decorative
+    ? { role: 'presentation', 'aria-hidden': true as const }
+    : {}
+  return <hr {...ariaProps} className={clsx(styles.divider, styles[spacing], className)} />
+}

package/dist/templates/with-reference-ds/design-system/src/components/Divider/index.ts

@@ -0,0 +1,2 @@
+export { Divider, type DividerProps, type DividerSpacing } from './Divider.js'
+export { contract as dividerContract } from './Divider.contract.js'

package/dist/templates/with-reference-ds/design-system/src/components/FAQ/FAQ.contract.ts

@@ -0,0 +1,104 @@
+import type { ComponentContract } from '@forumone/throughline-design-contract'
+
+export const contract: ComponentContract = {
+  name: 'FAQ',
+  category: 'data',
+  description:
+    'A disclosure-style question and answer list using native <details>/<summary> for keyboard accessibility with no JavaScript.',
+  intent:
+    'Answer the predictable questions readers arrive with. Use for program applications, purchase funnels, onboarding pages — anywhere the same three to ten questions come up repeatedly. Not for searchable knowledge bases (those need their own search UI).',
+
+  composition: {
+    placement: ['section'],
+    maxPerPage: 2,
+    requiredSiblings: [],
+    forbiddenAdjacent: [],
+  },
+
+  content: {
+    fields: [
+      {
+        name: 'headline',
+        type: 'text',
+        required: false,
+        maxLength: 100,
+      },
+      {
+        name: 'items',
+        type: 'array',
+        required: true,
+        constraints: 'Three to ten items; more than that needs its own dedicated page',
+        of: [
+          { name: 'question', type: 'text', required: true, maxLength: 200 },
+          { name: 'answer', type: 'richtext', required: true },
+        ],
+      },
+      {
+        name: 'defaultOpenFirst',
+        type: 'boolean',
+        required: false,
+        constraints: 'Set true when the first question is one readers always ask',
+      },
+    ],
+  },
+
+  tokens: {
+    consumes: [
+      'color.bg.primary',
+      'color.text.primary',
+      'color.text.secondary',
+      'color.border.default',
+      'color.border.strong',
+      'spacing.16',
+      'spacing.8',
+      'spacing.5',
+      'spacing.4',
+      'spacing.2',
+      'spacing.container',
+      'font.size.3xl',
+      'font.size.xl',
+      'font.weight.semibold',
+      'line.height.relaxed',
+      'radius.md',
+    ],
+  },
+
+  accessibility: {
+    keyboardSupport: [
+      'Tab to each question summary',
+      'Enter or Space opens/closes the current item',
+    ],
+    screenReaderBehavior:
+      'Each question is a <summary> inside <details>, so screen readers announce open/closed state natively. The answer becomes available to assistive tech when the item is expanded.',
+    contentWarnings: [
+      'Keep answers short and scannable — a paragraph at most',
+      'Do not nest FAQs inside FAQs',
+    ],
+  },
+
+  examples: [
+    { label: 'Default', intent: 'Program application FAQ', storyId: 'faq--default' },
+    { label: 'First item open', intent: 'Lead with the most common question already answered', storyId: 'faq--open-first' },
+    { label: 'Without headline', intent: 'Inline FAQ under a larger section', storyId: 'faq--no-headline' },
+  ],
+
+  antiExamples: [
+    {
+      label: 'Twenty-question FAQ',
+      why: 'Past about ten items the disclosure pattern breaks down; readers cannot scan the list',
+      useInstead: 'Split into topic-specific FAQs across multiple pages, or build a searchable knowledge base',
+    },
+    {
+      label: 'Using FAQ to hide primary content',
+      why: 'Important content should be visible by default, not hidden behind a click',
+      useInstead: 'Prose or a proper section with a SectionIntro',
+    },
+  ],
+
+  behavior: {
+    fetchesData: false,
+    hasClientState: true,
+    animates: false,
+    requiresAnalytics: false,
+  },
+}

package/dist/templates/with-reference-ds/design-system/src/components/FAQ/FAQ.module.css

@@ -0,0 +1,66 @@
+.faq {
+  padding: var(--spacing-16) 0;
+}
+
+.container {
+  max-width: 48rem;
+  margin: 0 auto;
+  padding: 0 var(--spacing-container);
+}
+
+.headline {
+  font-size: var(--font-size-3xl);
+  font-weight: var(--font-weight-semibold);
+  margin-bottom: var(--spacing-8);
+}
+
+.list {
+  list-style: none;
+  padding: 0;
+  margin: 0;
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-2);
+}
+
+.item {
+  border: 1px solid var(--color-border-default);
+  border-radius: var(--radius-md);
+  background: var(--color-bg-primary);
+  overflow: hidden;
+}
+
+.item[open] {
+  border-color: var(--color-border-strong);
+}
+
+.question {
+  cursor: pointer;
+  list-style: none;
+  padding: var(--spacing-4) var(--spacing-5);
+  font-weight: var(--font-weight-semibold);
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--spacing-4);
+}
+
+.question::-webkit-details-marker {
+  display: none;
+}
+
+.chevron {
+  color: var(--color-text-secondary);
+  font-size: var(--font-size-xl);
+  transition: transform 0.15s ease;
+}
+
+.item[open] .chevron {
+  transform: rotate(45deg);
+}
+
+.answer {
+  padding: 0 var(--spacing-5) var(--spacing-5);
+  color: var(--color-text-secondary);
+  line-height: var(--line-height-relaxed);
+}

package/dist/templates/with-reference-ds/design-system/src/components/FAQ/FAQ.stories.tsx

@@ -0,0 +1,61 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { FAQ } from './FAQ.js'
+
+const meta: Meta<typeof FAQ> = {
+  title: 'FAQ',
+  component: FAQ,
+}
+
+export default meta
+
+type Story = StoryObj<typeof FAQ>
+
+export const Default: Story = {
+  args: {
+    headline: 'Frequently asked questions',
+    items: [
+      {
+        question: 'Who is eligible to apply?',
+        answer:
+          'Researchers affiliated with accredited institutions whose work intersects climate and community resilience.',
+      },
+      {
+        question: 'When is the application deadline?',
+        answer:
+          'Applications close on October 15th. Decisions are announced by December 1st of the same year.',
+      },
+      {
+        question: 'What funding is available?',
+        answer: 'Grants range from $25,000 to $100,000 depending on the scope of the project.',
+      },
+    ],
+  },
+}
+
+export const OpenFirst: Story = {
+  args: {
+    defaultOpenFirst: true,
+    headline: 'Common questions',
+    items: [
+      {
+        question: 'Can I request an extension?',
+        answer: 'Yes, one 30-day extension is allowed per application cycle.',
+      },
+      {
+        question: 'What does the reporting look like?',
+        answer: 'A mid-grant report at six months and a final report at twelve months.',
+      },
+    ],
+  },
+}
+
+export const NoHeadline: Story = {
+  args: {
+    items: [
+      {
+        question: 'Is my data private?',
+        answer: 'All submissions are confidential and visible only to the review committee.',
+      },
+    ],
+  },
+}

package/dist/templates/with-reference-ds/design-system/src/components/FAQ/FAQ.test.tsx

@@ -0,0 +1,30 @@
+import { render, screen } from '@testing-library/react'
+import { describe, expect, it } from 'vitest'
+import { FAQ } from './FAQ.js'
+
+describe('FAQ', () => {
+  const items = [
+    { question: 'Q1', answer: 'A1' },
+    { question: 'Q2', answer: 'A2' },
+  ]
+
+  it('renders each question inside a details/summary', () => {
+    const { container } = render(<FAQ items={items} />)
+    const details = container.querySelectorAll('details')
+    expect(details).toHaveLength(2)
+    expect(screen.getByText('Q1')).toBeInTheDocument()
+    expect(screen.getByText('Q2')).toBeInTheDocument()
+  })
+
+  it('opens the first item when defaultOpenFirst is true', () => {
+    const { container } = render(<FAQ items={items} defaultOpenFirst />)
+    const details = container.querySelectorAll('details')
+    expect(details[0]).toHaveAttribute('open')
+    expect(details[1]).not.toHaveAttribute('open')
+  })
+
+  it('renders the headline as h2 when provided', () => {
+    render(<FAQ headline="Help" items={items} />)
+    expect(screen.getByRole('heading', { level: 2 })).toHaveTextContent('Help')
+  })
+})