@forumone/create-throughline 0.2.0 → 0.3.0

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

@@ -0,0 +1,37 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { MediaBlock } from './MediaBlock.js'
+
+const meta: Meta<typeof MediaBlock> = {
+  title: 'Media Block',
+  component: MediaBlock,
+}
+
+export default meta
+
+type Story = StoryObj<typeof MediaBlock>
+
+export const Image: Story = {
+  args: {
+    media: { type: 'image', url: 'https://placehold.co/1600x900', alt: 'Foundation staff at work' },
+    caption: 'Team members gathered for the annual retreat.',
+  },
+}
+
+export const Square: Story = {
+  args: {
+    aspect: 'square',
+    media: { type: 'image', url: 'https://placehold.co/800x800', alt: 'Portrait' },
+  },
+}
+
+export const Video: Story = {
+  args: {
+    media: {
+      type: 'video',
+      url: 'https://example.com/clip.mp4',
+      poster: 'https://placehold.co/1600x900',
+      ariaLabel: 'Introduction video',
+    },
+    caption: 'A three-minute introduction to the program.',
+  },
+}

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

@@ -0,0 +1,35 @@
+import { render, screen } from '@testing-library/react'
+import { describe, expect, it } from 'vitest'
+import { MediaBlock } from './MediaBlock.js'
+
+describe('MediaBlock', () => {
+  it('renders an image with alt text', () => {
+    render(
+      <MediaBlock media={{ type: 'image', url: '/pic.jpg', alt: 'A picture' }} />,
+    )
+    expect(screen.getByRole('img', { name: 'A picture' })).toHaveAttribute('src', '/pic.jpg')
+  })
+
+  it('renders a caption inside a figcaption when provided', () => {
+    render(
+      <MediaBlock
+        media={{ type: 'image', url: '/pic.jpg', alt: 'x' }}
+        caption="Explanatory caption"
+      />,
+    )
+    const caption = screen.getByText('Explanatory caption')
+    expect(caption.tagName.toLowerCase()).toBe('figcaption')
+  })
+
+  it('renders a video element with aria-label and poster', () => {
+    const { container } = render(
+      <MediaBlock
+        media={{ type: 'video', url: '/clip.mp4', poster: '/poster.jpg', ariaLabel: 'Intro' }}
+      />,
+    )
+    const video = container.querySelector('video')
+    expect(video).not.toBeNull()
+    expect(video).toHaveAttribute('aria-label', 'Intro')
+    expect(video).toHaveAttribute('poster', '/poster.jpg')
+  })
+})

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

@@ -0,0 +1,49 @@
+import { clsx } from 'clsx'
+import styles from './MediaBlock.module.css'
+
+export type MediaBlockAspect = '16:9' | '4:3' | 'square' | 'auto'
+
+type ImageMedia = { type: 'image'; url: string; alt: string }
+type VideoMedia = {
+  type: 'video'
+  url: string
+  poster?: string
+  /** Accessible label used when the video lacks audio/captions narrative context. */
+  ariaLabel?: string
+}
+
+export type MediaBlockMedia = ImageMedia | VideoMedia
+
+export interface MediaBlockProps {
+  media: MediaBlockMedia
+  caption?: string
+  aspect?: MediaBlockAspect
+  className?: string
+}
+
+export function MediaBlock({
+  media,
+  caption,
+  aspect = '16:9',
+  className,
+}: MediaBlockProps) {
+  const aspectKey = aspect === '16:9' ? 'aspect16x9' : aspect === '4:3' ? 'aspect4x3' : `aspect-${aspect}`
+  return (
+    <figure className={clsx(styles.figure, className)}>
+      <div className={clsx(styles.frame, styles[aspectKey])}>
+        {media.type === 'image' ? (
+          <img src={media.url} alt={media.alt} className={styles.media} />
+        ) : (
+          <video
+            src={media.url}
+            poster={media.poster}
+            controls
+            aria-label={media.ariaLabel}
+            className={styles.media}
+          />
+        )}
+      </div>
+      {caption ? <figcaption className={styles.caption}>{caption}</figcaption> : null}
+    </figure>
+  )
+}

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

@@ -0,0 +1,7 @@
+export {
+  MediaBlock,
+  type MediaBlockAspect,
+  type MediaBlockMedia,
+  type MediaBlockProps,
+} from './MediaBlock.js'
+export { contract as mediaBlockContract } from './MediaBlock.contract.js'

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

@@ -0,0 +1,107 @@
+import type { ComponentContract } from '@forumone/throughline-design-contract'
+
+export const contract: ComponentContract = {
+  name: 'Prose',
+  category: 'section',
+  description:
+    'A typographic container for long-form content — articles, policies, documentation, any flowing prose with headings and lists.',
+  intent:
+    'Wrap free-flowing editorial content with sensible typography defaults (heading hierarchy, paragraph rhythm, list styling, blockquote treatment). Use any time you have a block of content authored as rich text and you want it to read well without styling each element individually.',
+
+  composition: {
+    placement: ['section'],
+    maxPerPage: null,
+    requiredSiblings: [],
+    forbiddenAdjacent: [],
+  },
+
+  content: {
+    fields: [
+      {
+        name: 'children',
+        type: 'richtext',
+        required: true,
+        constraints:
+          'Rich text content authored in the CMS; can include h2-h4, paragraphs, lists, blockquotes, links',
+      },
+    ],
+    variants: [
+      {
+        name: 'default',
+        description: 'Standard reading rhythm',
+        whenToUse: 'Most articles and editorial content',
+      },
+      {
+        name: 'compact',
+        description: 'Tighter spacing and line height',
+        whenToUse: 'Denser reference content, product docs, or reading-room pages',
+      },
+      {
+        name: 'spacious',
+        description: 'Looser spacing and line height',
+        whenToUse: 'Long-form essays where the reader benefits from breathing room',
+      },
+    ],
+  },
+
+  tokens: {
+    consumes: [
+      'color.text.primary',
+      'color.text.secondary',
+      'color.border.strong',
+      'color.brand.primary',
+      'spacing.container',
+      'spacing.10',
+      'spacing.8',
+      'spacing.6',
+      'spacing.5',
+      'spacing.4',
+      'spacing.2',
+      'font.size.3xl',
+      'font.size.2xl',
+      'font.size.xl',
+      'font.size.lg',
+      'font.weight.semibold',
+      'line.height.snug',
+      'line.height.normal',
+      'line.height.relaxed',
+      'line.height.loose',
+    ],
+  },
+
+  accessibility: {
+    keyboardSupport: [],
+    screenReaderBehavior:
+      'Children render as their native semantic HTML (h2, h3, p, ul, ol, blockquote, a). Prose adds no ARIA beyond what the authored content provides.',
+    contentWarnings: [
+      'Author h2 and below inside Prose; never h1 (the page already has one)',
+      'Use real list markup, not paragraphs with bullets',
+    ],
+  },
+
+  examples: [
+    { label: 'Default', intent: 'Standard article body', storyId: 'prose--default' },
+    { label: 'Compact', intent: 'Reference or documentation page', storyId: 'prose--compact' },
+    { label: 'Spacious', intent: 'Long-form essay or manifesto', storyId: 'prose--spacious' },
+  ],
+
+  antiExamples: [
+    {
+      label: 'Nesting Prose inside Prose',
+      why: 'Creates duplicate typography scales and unpredictable spacing',
+      useInstead: 'Use a single Prose at the outermost level',
+    },
+    {
+      label: 'Putting interactive components inside Prose',
+      why: 'Prose is for flowing editorial content; components like Stats or CardGrid have their own layout',
+      useInstead: 'Close the Prose, render the component, open another Prose for continuing text',
+    },
+  ],
+
+  behavior: {
+    fetchesData: false,
+    hasClientState: false,
+    animates: false,
+    requiresAnalytics: false,
+  },
+}

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

@@ -0,0 +1,72 @@
+.prose {
+  max-width: 42rem;
+  margin: 0 auto;
+  padding: 0 var(--spacing-container);
+  color: var(--color-text-primary);
+  line-height: var(--line-height-relaxed);
+}
+
+.prose > * + * {
+  margin-top: var(--spacing-5);
+}
+
+.prose h2 {
+  font-size: var(--font-size-3xl);
+  font-weight: var(--font-weight-semibold);
+  line-height: var(--line-height-snug);
+  margin-top: var(--spacing-10);
+}
+
+.prose h3 {
+  font-size: var(--font-size-2xl);
+  font-weight: var(--font-weight-semibold);
+  line-height: var(--line-height-snug);
+  margin-top: var(--spacing-8);
+}
+
+.prose h4 {
+  font-size: var(--font-size-xl);
+  font-weight: var(--font-weight-semibold);
+}
+
+.prose p {
+  font-size: var(--font-size-lg);
+}
+
+.prose a {
+  color: var(--color-brand-primary);
+  text-decoration: underline;
+  text-underline-offset: 0.15em;
+}
+
+.prose ul,
+.prose ol {
+  padding-inline-start: var(--spacing-6);
+}
+
+.prose li + li {
+  margin-top: var(--spacing-2);
+}
+
+.prose blockquote {
+  border-inline-start: 3px solid var(--color-border-strong);
+  padding-inline-start: var(--spacing-4);
+  color: var(--color-text-secondary);
+  font-style: italic;
+}
+
+.compact {
+  line-height: var(--line-height-normal);
+}
+
+.compact > * + * {
+  margin-top: var(--spacing-4);
+}
+
+.spacious {
+  line-height: var(--line-height-loose);
+}
+
+.spacious > * + * {
+  margin-top: var(--spacing-6);
+}

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

@@ -0,0 +1,39 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { Prose } from './Prose.js'
+
+const meta: Meta<typeof Prose> = {
+  title: 'Prose',
+  component: Prose,
+}
+
+export default meta
+
+type Story = StoryObj<typeof Prose>
+
+const sampleContent = (
+  <>
+    <h2>Why content-first CMSes matter</h2>
+    <p>
+      A content management system should help editorial teams describe the world accurately, not
+      force them into a grid of tiles and buckets. When the CMS models the world well, the rest of
+      the work — rendering, governance, publication — becomes tractable.
+    </p>
+    <h3>The three pillars</h3>
+    <ul>
+      <li>Content models that describe intent, not layout</li>
+      <li>Governance that encodes approval policy</li>
+      <li>Publication that&apos;s reversible and auditable</li>
+    </ul>
+    <blockquote>
+      &ldquo;The best CMS is the one your editors forget they are using.&rdquo;
+    </blockquote>
+    <p>
+      Everything else is detail. The reference design system exists to prove the framework can
+      ship a working, accessible, and accountable editorial experience with just a dozen components.
+    </p>
+  </>
+)
+
+export const Default: Story = { args: { children: sampleContent } }
+export const Compact: Story = { args: { size: 'compact', children: sampleContent } }
+export const Spacious: Story = { args: { size: 'spacious', children: sampleContent } }

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

@@ -0,0 +1,26 @@
+import { render, screen } from '@testing-library/react'
+import { describe, expect, it } from 'vitest'
+import { Prose } from './Prose.js'
+
+describe('Prose', () => {
+  it('renders child headings with their native semantics', () => {
+    render(
+      <Prose>
+        <h2>Section</h2>
+        <p>Body</p>
+      </Prose>,
+    )
+    expect(screen.getByRole('heading', { level: 2 })).toHaveTextContent('Section')
+    expect(screen.getByText('Body')).toBeInTheDocument()
+  })
+
+  it('applies size variants', () => {
+    const { container } = render(
+      <Prose size="compact">
+        <p>One</p>
+      </Prose>,
+    )
+    const root = container.firstChild as HTMLElement
+    expect(root.className).toContain('compact')
+  })
+})

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

@@ -0,0 +1,15 @@
+import { clsx } from 'clsx'
+import type { ReactNode } from 'react'
+import styles from './Prose.module.css'
+
+export type ProseSize = 'default' | 'compact' | 'spacious'
+
+export interface ProseProps {
+  children: ReactNode
+  size?: ProseSize
+  className?: string
+}
+
+export function Prose({ children, size = 'default', className }: ProseProps) {
+  return <div className={clsx(styles.prose, styles[size], className)}>{children}</div>
+}

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

@@ -0,0 +1,2 @@
+export { Prose, type ProseProps, type ProseSize } from './Prose.js'
+export { contract as proseContract } from './Prose.contract.js'

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

@@ -0,0 +1,101 @@
+import type { ComponentContract } from '@forumone/throughline-design-contract'
+
+export const contract: ComponentContract = {
+  name: 'Quote',
+  category: 'media',
+  description:
+    'A pullquote or testimonial rendered as a <figure> with a <blockquote> and optional figcaption attribution.',
+  intent:
+    'Surface a single human-scale quotation — a testimonial, a pullquote, a foundational claim. Use sparingly; quotes lose weight when stacked. The attribution is optional because some quotes stand on their own without a named author.',
+
+  composition: {
+    placement: ['section'],
+    maxPerPage: null,
+    requiredSiblings: [],
+    forbiddenAdjacent: ['Quote'],
+  },
+
+  content: {
+    fields: [
+      {
+        name: 'quote',
+        type: 'text',
+        required: true,
+        maxLength: 400,
+        constraints: 'One or two sentences; longer belongs in Prose',
+      },
+      {
+        name: 'attribution',
+        type: 'group',
+        required: false,
+        of: [
+          { name: 'name', type: 'text', required: true, maxLength: 80 },
+          { name: 'role', type: 'text', required: false, maxLength: 100 },
+          { name: 'avatar', type: 'image', required: false },
+        ],
+      },
+    ],
+    variants: [
+      { name: 'default', description: 'Standard size', whenToUse: 'Most testimonials and pullquotes' },
+      { name: 'large', description: 'Oversized display treatment', whenToUse: 'Editorial openers or mission-page quotes that carry real weight' },
+    ],
+  },
+
+  tokens: {
+    consumes: [
+      'color.text.primary',
+      'color.text.secondary',
+      'spacing.10',
+      'spacing.6',
+      'spacing.3',
+      'spacing.container',
+      'font.size.4xl',
+      'font.size.2xl',
+      'font.size.sm',
+      'font.weight.semibold',
+      'line.height.tight',
+      'line.height.snug',
+      'radius.full',
+    ],
+    configurable: [
+      { prop: 'size', tokenGroup: 'layout', allowedValues: ['default', 'large'] },
+    ],
+  },
+
+  accessibility: {
+    keyboardSupport: [],
+    screenReaderBehavior:
+      'Rendered as <figure> containing a <blockquote>; attribution is read as the figcaption. Decorative quotation marks are generated via CSS and are not in the accessible name.',
+    contentWarnings: [
+      'Do not quote someone without permission',
+      'Use their actual words; a paraphrase inside quotation marks misrepresents them',
+    ],
+  },
+
+  examples: [
+    { label: 'Default', intent: 'Testimonial with role', storyId: 'quote--default' },
+    { label: 'With avatar', intent: 'Testimonial with portrait', storyId: 'quote--with-avatar' },
+    { label: 'Large', intent: 'Editorial mission statement', storyId: 'quote--large' },
+    { label: 'Without attribution', intent: 'Aphoristic pullquote', storyId: 'quote--without-attribution' },
+  ],
+
+  antiExamples: [
+    {
+      label: 'Four quotes in a row',
+      why: 'Quote is meant to punctuate content, not fill a page',
+      useInstead: 'Pick the strongest quote; move the rest into Prose or a CardGrid of Cards',
+    },
+    {
+      label: 'Using Quote for product blurbs',
+      why: 'Quote implies a real human author; marketing copy without a source undermines trust',
+      useInstead: 'CTASection or Prose',
+    },
+  ],
+
+  behavior: {
+    fetchesData: false,
+    hasClientState: false,
+    animates: false,
+    requiresAnalytics: false,
+  },
+}

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

@@ -0,0 +1,59 @@
+.figure {
+  max-width: 48rem;
+  margin: 0 auto;
+  padding: var(--spacing-10) var(--spacing-container);
+  text-align: center;
+}
+
+.quote {
+  margin: 0 0 var(--spacing-6);
+  font-style: italic;
+}
+
+.quote p {
+  font-size: var(--font-size-2xl);
+  line-height: var(--line-height-snug);
+  color: var(--color-text-primary);
+  margin: 0;
+}
+
+.large .quote p {
+  font-size: var(--font-size-4xl);
+  line-height: var(--line-height-tight);
+}
+
+.quote p::before {
+  content: '\201C';
+  margin-right: 0.1em;
+}
+
+.quote p::after {
+  content: '\201D';
+  margin-left: 0.1em;
+}
+
+.attribution {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--spacing-3);
+  color: var(--color-text-secondary);
+  font-size: var(--font-size-sm);
+  font-style: normal;
+}
+
+.avatar {
+  width: 2.5rem;
+  height: 2.5rem;
+  border-radius: var(--radius-full);
+  object-fit: cover;
+}
+
+.name {
+  font-weight: var(--font-weight-semibold);
+  color: var(--color-text-primary);
+}
+
+.role::before {
+  content: '\00B7';
+  margin: 0 0.25em;
+}

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

@@ -0,0 +1,44 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { Quote } from './Quote.js'
+
+const meta: Meta<typeof Quote> = {
+  title: 'Quote',
+  component: Quote,
+}
+
+export default meta
+
+type Story = StoryObj<typeof Quote>
+
+export const Default: Story = {
+  args: {
+    quote:
+      'The best CMS is the one your editorial team forgets they are using.',
+    attribution: { name: 'Jordan Rivers', role: 'Design director' },
+  },
+}
+
+export const WithAvatar: Story = {
+  args: {
+    quote:
+      'After we moved to a content-first model, our publishing velocity nearly doubled without adding to the team.',
+    attribution: {
+      name: 'Maria Santos',
+      role: 'Head of content, Greenfield Foundation',
+      avatar: { url: 'https://placehold.co/80x80', alt: 'Portrait of Maria Santos' },
+    },
+  },
+}
+
+export const Large: Story = {
+  args: {
+    size: 'large',
+    quote: 'Editorial teams deserve tools that take their workflows seriously.',
+  },
+}
+
+export const WithoutAttribution: Story = {
+  args: {
+    quote: 'Content first. Everything else follows.',
+  },
+}

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

@@ -0,0 +1,37 @@
+import { render, screen } from '@testing-library/react'
+import { describe, expect, it } from 'vitest'
+import { Quote } from './Quote.js'
+
+describe('Quote', () => {
+  it('renders the quote inside a blockquote', () => {
+    const { container } = render(<Quote quote="Content first." />)
+    expect(container.querySelector('blockquote')).not.toBeNull()
+    expect(screen.getByText('Content first.')).toBeInTheDocument()
+  })
+
+  it('renders the attribution inside a figcaption when provided', () => {
+    const { container } = render(
+      <Quote
+        quote="Words."
+        attribution={{ name: 'Ada Lovelace', role: 'Mathematician' }}
+      />,
+    )
+    const caption = container.querySelector('figcaption')
+    expect(caption).not.toBeNull()
+    expect(caption).toHaveTextContent('Ada Lovelace')
+    expect(caption).toHaveTextContent('Mathematician')
+  })
+
+  it('renders an avatar when attribution includes one', () => {
+    render(
+      <Quote
+        quote="Words."
+        attribution={{
+          name: 'Grace Hopper',
+          avatar: { url: '/avatar.jpg', alt: 'Grace Hopper portrait' },
+        }}
+      />,
+    )
+    expect(screen.getByRole('img', { name: 'Grace Hopper portrait' })).toBeInTheDocument()
+  })
+})

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

@@ -0,0 +1,40 @@
+import { clsx } from 'clsx'
+import styles from './Quote.module.css'
+
+export type QuoteSize = 'default' | 'large'
+
+export interface QuoteProps {
+  quote: string
+  attribution?: {
+    name: string
+    role?: string
+    avatar?: { url: string; alt: string }
+  }
+  size?: QuoteSize
+  className?: string
+}
+
+export function Quote({ quote, attribution, size = 'default', className }: QuoteProps) {
+  return (
+    <figure className={clsx(styles.figure, styles[size], className)}>
+      <blockquote className={styles.quote}>
+        <p>{quote}</p>
+      </blockquote>
+      {attribution ? (
+        <figcaption className={styles.attribution}>
+          {attribution.avatar ? (
+            <img
+              src={attribution.avatar.url}
+              alt={attribution.avatar.alt}
+              className={styles.avatar}
+            />
+          ) : null}
+          <span className={styles.name}>{attribution.name}</span>
+          {attribution.role ? (
+            <span className={styles.role}>{attribution.role}</span>
+          ) : null}
+        </figcaption>
+      ) : null}
+    </figure>
+  )
+}

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

@@ -0,0 +1,2 @@
+export { Quote, type QuoteProps, type QuoteSize } from './Quote.js'
+export { contract as quoteContract } from './Quote.contract.js'