aural-ui 4.0.1 → 4.1.0

package/dist/components/typography/Typography.stories.tsx

@@ -1,6 +1,8 @@
 import React from "react"
 import type { Meta, StoryObj } from "@storybook/react-vite"
 
+import { AuralComponentDocsPage } from "src/ui/story-spec/components/component-story-docs-page"
+
 import {
   BodyLarge,
   BodyMedium,
@@ -23,17 +25,34 @@ import {
 const meta: Meta<typeof Typography> = {
   title: "Components/UI/Typography",
   component: Typography,
+  tags: ["autodocs"],
   parameters: {
     layout: "centered",
-    backgrounds: {
-      default: "dark",
-      values: [
-        { name: "dark", value: "#0a0a0a" },
-        { name: "light", value: "#ffffff" },
-      ],
+    docs: {
+      description: {
+        component:
+          "A polymorphic text primitive covering the full design-system type scale — Display, Title, Label, Body, and Caption — each in three sizes. Supports weight, alignment, color, text-transform, line-height, and text-wrap axes via props, and can render as any semantic HTML element via the `as` prop.",
+      },
+      page: () => (
+        <AuralComponentDocsPage
+          features={[
+            {
+              title: "5 Type Roles",
+              description: "Display to caption",
+            },
+            {
+              title: "Polymorphic",
+              description: "Render as any element",
+            },
+            {
+              title: "Full Style Axes",
+              description: "Weight, align, color",
+            },
+          ]}
+        />
+      ),
     },
   },
-  tags: ["autodocs"],
   argTypes: {
     variant: {
       control: "select",
@@ -54,34 +73,42 @@ const meta: Meta<typeof Typography> = {
         "caption-medium",
         "caption-small",
       ],
+      description: "Type scale variant",
     },
     weight: {
       control: "select",
       options: ["regular", "medium", "semibold", "bold"],
+      description: "Font weight",
     },
     align: {
       control: "radio",
       options: ["left", "center", "right"],
+      description: "Text alignment",
     },
     color: {
       control: "select",
       options: ["primary", "secondary", "tertiary", "contrast", "inactive"],
+      description: "Semantic text color",
     },
     transform: {
       control: "select",
       options: ["uppercase", "lowercase", "capitalize", "normal"],
+      description: "CSS text-transform",
     },
     lineHeight: {
       control: "select",
-      options: ["tight", "normal", "loose"],
+      options: ["tight", "normal", "loose", "auto"],
+      description: "Override line-height",
     },
     wrap: {
       control: "select",
       options: ["normal", "nowrap", "wrap", "pretty", "balance"],
+      description: "CSS text-wrap",
     },
     as: {
       control: "select",
       options: ["p", "span", "div", "h1", "h2", "h3", "h4", "h5", "h6"],
+      description: "HTML element to render",
     },
   },
 }
@@ -89,116 +116,406 @@ const meta: Meta<typeof Typography> = {
 export default meta
 type Story = StoryObj<typeof Typography>
 
-export const Default: Story = {
+// ─── 1. Playground ────────────────────────────────────────────────────────────
+
+export const Playground: Story = {
   args: {
     children: "The quick brown fox jumps over the lazy dog",
     variant: "body-medium",
     weight: "regular",
     color: "primary",
     align: "left",
+    transform: "normal",
+    lineHeight: "auto",
+  },
+  render: (args) => (
+    <div className="w-full max-w-lg space-y-4">
+      <Typography {...args} />
+      <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border px-4 py-3">
+        <code className="text-fm-secondary text-fm-md leading-fm-md font-(--font-fm-mono)">{`<Typography variant="${args.variant}" weight="${args.weight}" color="${args.color}">`}</code>
+      </div>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Adjust variant, weight, color, align, transform, and lineHeight using the controls panel in the sidebar.",
+      },
+    },
   },
 }
 
-export const AllVariants = () => {
-  return (
-    <div className="bg-fm-surface-primary flex flex-col gap-6 p-4">
+// ─── 2. All Variants ──────────────────────────────────────────────────────────
+
+export const AllVariants: Story = {
+  render: () => (
+    <div className="space-y-8">
+      {/* Display scale */}
       <div className="space-y-4">
-        <DisplayLarge className="mb-2">Display Large</DisplayLarge>
-        <DisplayMedium className="mb-2">Display Medium</DisplayMedium>
-        <DisplaySmall className="mb-2">Display Small</DisplaySmall>
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Display
+        </h4>
+        <div className="space-y-3">
+          <div className="space-y-1">
+            <DisplayLarge>Display Large</DisplayLarge>
+            <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm">
+              display-large · 58px / 72px · PP Supply Sans
+            </p>
+          </div>
+          <div className="space-y-1">
+            <DisplayMedium>Display Medium</DisplayMedium>
+            <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm">
+              display-medium · 46px / 54px · PP Supply Sans
+            </p>
+          </div>
+          <div className="space-y-1">
+            <DisplaySmall>Display Small</DisplaySmall>
+            <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm">
+              display-small · 40px / 46px · PP Supply Sans
+            </p>
+          </div>
+        </div>
       </div>
 
+      {/* Title scale */}
       <div className="space-y-4">
-        <TitleLarge className="mb-2">Title Large</TitleLarge>
-        <TitleMedium className="mb-2">Title Medium</TitleMedium>
-        <TitleSmall className="mb-2">Title Small</TitleSmall>
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Title
+        </h4>
+        <div className="space-y-3">
+          <div className="space-y-1">
+            <TitleLarge>Title Large</TitleLarge>
+            <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm">
+              title-large · 36px / 42px · PP Supply Sans
+            </p>
+          </div>
+          <div className="space-y-1">
+            <TitleMedium>Title Medium</TitleMedium>
+            <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm">
+              title-medium · 32px / 38px · PP Supply Sans
+            </p>
+          </div>
+          <div className="space-y-1">
+            <TitleSmall>Title Small</TitleSmall>
+            <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm">
+              title-small · 28px / 32px · PP Supply Sans
+            </p>
+          </div>
+        </div>
       </div>
 
+      {/* Label scale */}
       <div className="space-y-4">
-        <LabelLarge className="mb-2 block">Label Large</LabelLarge>
-        <LabelMedium className="mb-2 block">Label Medium</LabelMedium>
-        <LabelSmall className="mb-2 block">Label Small</LabelSmall>
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Label
+        </h4>
+        <div className="space-y-3">
+          <div className="space-y-1">
+            <LabelLarge className="block">Label Large</LabelLarge>
+            <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm">
+              label-large · 24px / 28px · PP Supply Sans
+            </p>
+          </div>
+          <div className="space-y-1">
+            <LabelMedium className="block">Label Medium</LabelMedium>
+            <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm">
+              label-medium · 20px / 24px · PP Supply Sans
+            </p>
+          </div>
+          <div className="space-y-1">
+            <LabelSmall className="block">Label Small</LabelSmall>
+            <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm">
+              label-small · 16px / 20px · PP Supply Sans
+            </p>
+          </div>
+        </div>
       </div>
 
+      {/* Body scale */}
       <div className="space-y-4">
-        <BodyLarge className="mb-2">Body Large</BodyLarge>
-        <BodyMedium className="mb-2">Body Medium</BodyMedium>
-        <BodySmall className="mb-2">Body Small</BodySmall>
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Body
+        </h4>
+        <div className="space-y-3">
+          <div className="space-y-1">
+            <BodyLarge>
+              Body Large — The quick brown fox jumps over the lazy dog.
+            </BodyLarge>
+            <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm">
+              body-large · 20px / 24px · Lab Grotesque
+            </p>
+          </div>
+          <div className="space-y-1">
+            <BodyMedium>
+              Body Medium — The quick brown fox jumps over the lazy dog.
+            </BodyMedium>
+            <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm">
+              body-medium · 16px / 20px · Lab Grotesque
+            </p>
+          </div>
+          <div className="space-y-1">
+            <BodySmall>
+              Body Small — The quick brown fox jumps over the lazy dog.
+            </BodySmall>
+            <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm">
+              body-small · 14px / 18px · Lab Grotesque
+            </p>
+          </div>
+        </div>
       </div>
 
+      {/* Caption scale */}
       <div className="space-y-4">
-        <CaptionLarge className="mb-2 block">Caption Large</CaptionLarge>
-        <CaptionMedium className="mb-2 block">Caption Medium</CaptionMedium>
-        <CaptionSmall className="mb-2 block">Caption Small</CaptionSmall>
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Caption
+        </h4>
+        <div className="space-y-3">
+          <div className="space-y-1">
+            <CaptionLarge className="block">
+              Caption Large — Supporting metadata and labels
+            </CaptionLarge>
+            <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm">
+              caption-large · 14px / 18px · Lab Grotesque
+            </p>
+          </div>
+          <div className="space-y-1">
+            <CaptionMedium className="block">
+              Caption Medium — Supporting metadata and labels
+            </CaptionMedium>
+            <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm">
+              caption-medium · 12px / 16px · Lab Grotesque
+            </p>
+          </div>
+          <div className="space-y-1">
+            <CaptionSmall className="block">
+              Caption Small — Supporting metadata and labels
+            </CaptionSmall>
+            <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm">
+              caption-small · 10px / 12px · Lab Grotesque
+            </p>
+          </div>
+        </div>
       </div>
     </div>
-  )
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Complete type scale from Display Large (58px) down to Caption Small (10px). Each row shows the variant name, pixel size, line-height, and font family.",
+      },
+    },
+  },
 }
 
-export const WeightVariants = () => {
-  return (
-    <div className="bg-fm-surface-primary flex flex-col gap-4 p-4">
-      <Typography weight="regular">Regular weight text</Typography>
-      <Typography weight="medium">Medium weight text</Typography>
-      <Typography weight="semibold">Semibold weight text</Typography>
-      <Typography weight="bold">Bold weight text</Typography>
-    </div>
-  )
-}
+// ─── 3. Configurations ────────────────────────────────────────────────────────
 
-export const ColorVariants = () => {
-  return (
-    <div className="bg-fm-surface-primary flex flex-col gap-4 p-4">
-      <Typography color="primary">Primary color text</Typography>
-      <Typography color="secondary">Secondary color text</Typography>
-      <Typography color="tertiary">Tertiary color text</Typography>
-      <Typography color="contrast">Contrast color text</Typography>
-      <Typography color="inactive">Inactive color text</Typography>
-    </div>
-  )
-}
+export const Configurations: Story = {
+  render: () => (
+    <div className="space-y-8">
+      {/* Weight axis */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Weight
+        </h4>
+        <div className="flex flex-wrap gap-4">
+          <div className="space-y-2 text-center">
+            <Typography variant="body-large" weight="regular">
+              Regular
+            </Typography>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              regular (400)
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <Typography variant="body-large" weight="medium">
+              Medium
+            </Typography>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              medium (500)
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <Typography variant="body-large" weight="semibold">
+              Semibold
+            </Typography>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              semibold (600)
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <Typography variant="body-large" weight="bold">
+              Bold
+            </Typography>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              bold (700)
+            </p>
+          </div>
+        </div>
+      </div>
 
-export const AlignmentVariants = () => {
-  return (
-    <div className="bg-fm-surface-primary flex flex-col gap-4 p-4">
-      <Typography align="left">Left aligned text</Typography>
-      <Typography align="center">Center aligned text</Typography>
-      <Typography align="right">Right aligned text</Typography>
-    </div>
-  )
-}
+      {/* Color axis */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Color
+        </h4>
+        <div className="flex flex-wrap gap-4">
+          <div className="space-y-2 text-center">
+            <Typography variant="body-large" color="primary">
+              Primary
+            </Typography>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              primary
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <Typography variant="body-large" color="secondary">
+              Secondary
+            </Typography>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              secondary
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <Typography variant="body-large" color="tertiary">
+              Tertiary
+            </Typography>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              tertiary
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <Typography variant="body-large" color="inactive">
+              Inactive
+            </Typography>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              inactive
+            </p>
+          </div>
+        </div>
+      </div>
 
-export const TransformVariants = () => {
-  return (
-    <div className="bg-fm-surface-primary flex flex-col gap-4 p-4">
-      <Typography transform="uppercase">Uppercase text</Typography>
-      <Typography transform="lowercase">
-        Lowercase Text Will Appear Here
-      </Typography>
-      <Typography transform="capitalize">capitalize each word</Typography>
-      <Typography transform="normal">Normal text transform</Typography>
-    </div>
-  )
-}
+      {/* Alignment axis */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Alignment
+        </h4>
+        <div className="w-full max-w-md space-y-3">
+          <div className="border-fm-divider-secondary rounded-lg border p-3">
+            <Typography variant="body-medium" align="left">
+              Left-aligned text — the default reading direction.
+            </Typography>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm mt-1">
+              left
+            </p>
+          </div>
+          <div className="border-fm-divider-secondary rounded-lg border p-3">
+            <Typography variant="body-medium" align="center">
+              Center-aligned text — for headings and callouts.
+            </Typography>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm mt-1 text-center">
+              center
+            </p>
+          </div>
+          <div className="border-fm-divider-secondary rounded-lg border p-3">
+            <Typography variant="body-medium" align="right">
+              Right-aligned text — for numeric data or RTL contexts.
+            </Typography>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm mt-1 text-right">
+              right
+            </p>
+          </div>
+        </div>
+      </div>
 
-export const LineHeightVariants = () => {
-  return (
-    <div className="bg-fm-surface-primary flex flex-col gap-8 p-4">
-      <Typography lineHeight="tight">
-        Tight line height. Lorem ipsum dolor sit amet, consectetur adipiscing
-        elit. Nullam in dui mauris. Vivamus hendrerit arcu sed erat molestie
-        vehicula.
-      </Typography>
-      <Typography lineHeight="normal">
-        Normal line height. Lorem ipsum dolor sit amet, consectetur adipiscing
-        elit. Nullam in dui mauris. Vivamus hendrerit arcu sed erat molestie
-        vehicula.
-      </Typography>
-      <Typography lineHeight="loose">
-        Loose line height. Lorem ipsum dolor sit amet, consectetur adipiscing
-        elit. Nullam in dui mauris. Vivamus hendrerit arcu sed erat molestie
-        vehicula.
-      </Typography>
+      {/* Transform axis */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Text transform
+        </h4>
+        <div className="flex flex-wrap gap-4">
+          <div className="space-y-2 text-center">
+            <Typography variant="body-large" transform="normal">
+              Normal
+            </Typography>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              normal
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <Typography variant="body-large" transform="uppercase">
+              Uppercase
+            </Typography>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              uppercase
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <Typography variant="body-large" transform="capitalize">
+              capitalize each word
+            </Typography>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              capitalize
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <Typography variant="body-large" transform="lowercase">
+              LOWERCASE TEXT
+            </Typography>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              lowercase
+            </p>
+          </div>
+        </div>
+      </div>
+
+      {/* Line-height axis */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Line height override
+        </h4>
+        <div className="grid grid-cols-1 gap-4 sm:grid-cols-3">
+          <div className="border-fm-divider-secondary rounded-lg border p-3">
+            <Typography variant="body-medium" lineHeight="tight">
+              Tight line height. Lorem ipsum dolor sit amet, consectetur
+              adipiscing elit. Vivamus hendrerit arcu sed erat molestie
+              vehicula.
+            </Typography>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm mt-2">
+              tight
+            </p>
+          </div>
+          <div className="border-fm-divider-secondary rounded-lg border p-3">
+            <Typography variant="body-medium" lineHeight="normal">
+              Normal line height. Lorem ipsum dolor sit amet, consectetur
+              adipiscing elit. Vivamus hendrerit arcu sed erat molestie
+              vehicula.
+            </Typography>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm mt-2">
+              normal
+            </p>
+          </div>
+          <div className="border-fm-divider-secondary rounded-lg border p-3">
+            <Typography variant="body-medium" lineHeight="loose">
+              Loose line height. Lorem ipsum dolor sit amet, consectetur
+              adipiscing elit. Vivamus hendrerit arcu sed erat molestie
+              vehicula.
+            </Typography>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm mt-2">
+              loose
+            </p>
+          </div>
+        </div>
+      </div>
     </div>
-  )
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "One subsection per configuration axis: weight (regular → bold), color (primary → inactive), alignment (left / center / right), text-transform, and line-height override (tight / normal / loose).",
+      },
+    },
+  },
 }