aural-ui 4.0.1 → 4.1.0

package/dist/components/clamp-lines/ClampLines.stories.tsx

@@ -1,53 +1,85 @@
-import React from "react"
+import React, { useState } from "react"
 import type { Meta, StoryObj } from "@storybook/react-vite"
-import { toast } from "sonner"
+
+import { AuralComponentDocsPage } from "src/ui/story-spec/components/component-story-docs-page"
 
 import { ClampLines } from "."
-import { Toaster } from "../toast"
+import { Button } from "../button"
+
+// ─── Sample text in an audio-streaming context ──────────────────────────────
+
+const EPISODE_DESC =
+  "In this episode we sit down with Grammy-winning producer Anya Reeves to discuss the craft of mixing live orchestral recordings, the challenges of capturing room acoustics in modern studios, and how emerging spatial audio formats are reshaping the way listeners experience music at home. We also explore her recent collaboration with the Aural Collective on their debut album and what the future holds for independent artists distributing exclusively through streaming platforms."
 
-const LONG_TEXT =
-  "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum."
+const SHORT_BIO = "DJ Kai spins deep house and Afrobeats every Friday night."
 
 const meta: Meta<typeof ClampLines> = {
   title: "Components/UI/ClampLines",
   component: ClampLines,
   parameters: {
     layout: "centered",
-    backgrounds: {
-      default: "dark",
-      values: [
-        { name: "dark", value: "#0a0a0a" },
-        { name: "light", value: "#ffffff" },
-      ],
+    docs: {
+      description: {
+        component:
+          "A utility component for truncating long text blocks by word count or CSS line-clamp, with a built-in expand/collapse toggle. Ideal for podcast episode descriptions, artist bios, and playlist notes where text length is unpredictable.",
+      },
+      page: () => (
+        <AuralComponentDocsPage
+          features={[
+            {
+              title: "Word Limit",
+              description: "Truncate by word count",
+            },
+            {
+              title: "Responsive",
+              description: "No-JS fallback mode",
+            },
+            {
+              title: "Render Prop",
+              description: "Render-prop toggle",
+            },
+          ]}
+        />
+      ),
     },
   },
   tags: ["autodocs"],
   argTypes: {
     wordLimit: {
       control: "number",
-      description: "Max number of words to display before truncating",
+      description: "Max number of words shown before truncation.",
     },
     responsive: {
       control: "boolean",
-      description: "Adjusts word limit based on viewport width",
+      description:
+        "Scales the word limit proportionally to viewport width when true.",
     },
     minWordLimit: {
       control: "number",
       description:
-        "Minimum word limit used on small screens when responsive is true",
+        "Minimum word limit applied on the smallest viewports when responsive is true.",
+    },
+    readMoreText: {
+      control: "text",
+      description: "Label for the expand button.",
+    },
+    readLessText: {
+      control: "text",
+      description: "Label for the collapse button.",
     },
     button: {
       control: false,
       description:
-        "Render function for a custom toggle button. Receives `open` (boolean) and `toggle` (function) so the button can reflect and control expand/collapse state. Example: `(open, toggle) => <button onClick={toggle}>{open ? 'Less' : 'More'}</button>`",
+        "Render function for a fully custom toggle button. Receives `open` (boolean) and `toggle` (function). Return `null` to suppress the button entirely.",
     },
     classes: {
       control: "object",
-      description: "Override classes for root and button elements",
+      description:
+        "Class overrides for internal elements: `root`, `content`, `clampLineBtn`, `clampLineBtnInnerClass`.",
     },
     children: {
       control: "text",
-      description: "The text content to render",
+      description: "The text content to clamp.",
     },
   },
 }
@@ -55,115 +87,212 @@ const meta: Meta<typeof ClampLines> = {
 export default meta
 type Story = StoryObj<typeof ClampLines>
 
-export const Default: Story = {
-  args: {
-    children: LONG_TEXT,
-    wordLimit: 20,
-  },
-}
+// ─── 1. Configurations ───────────────────────────────────────────────────────
 
-export const WithCSSClamp: Story = {
-  name: "CSS Line Clamp (no wordLimit)",
-  args: {
-    children: LONG_TEXT,
-  },
-  decorators: [
-    (Story) => (
-      <div style={{ width: 400 }}>
-        <Story />
+export const Configurations: Story = {
+  render: () => (
+    <div className="space-y-8" style={{ width: 440 }}>
+      {/* Word limit */}
+      <div>
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md mb-4 font-medium">
+          Word Limit
+        </h4>
+        <div className="space-y-6">
+          <div className="space-y-2">
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              20 words
+            </p>
+            <ClampLines wordLimit={20}>{EPISODE_DESC}</ClampLines>
+          </div>
+          <div className="space-y-2">
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              40 words
+            </p>
+            <ClampLines wordLimit={40}>{EPISODE_DESC}</ClampLines>
+          </div>
+          <div className="space-y-2">
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              CSS line-clamp — 3 lines (no wordLimit)
+            </p>
+            <ClampLines>{EPISODE_DESC}</ClampLines>
+          </div>
+          <div className="space-y-2">
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Short text — no truncation triggered
+            </p>
+            <ClampLines wordLimit={30}>{SHORT_BIO}</ClampLines>
+          </div>
+        </div>
       </div>
-    ),
-  ],
-}
 
-export const Responsive: Story = {
-  args: {
-    children: LONG_TEXT,
-    wordLimit: 40,
-    responsive: true,
-    minWordLimit: 10,
-  },
-}
+      {/* Responsive mode */}
+      <div>
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md mb-4 font-medium">
+          Responsive Mode
+        </h4>
+        <div className="space-y-2">
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            wordLimit=50, minWordLimit=15 — resize the viewport to see the limit
+            adapt
+          </p>
+          <ClampLines wordLimit={50} responsive minWordLimit={15}>
+            {EPISODE_DESC}
+          </ClampLines>
+        </div>
+      </div>
 
-export const WithCustomButton: Story = {
-  name: "Custom Button",
-  args: {
-    children: LONG_TEXT,
-    wordLimit: 20,
-    button: (open, toggle) => (
-      <button
-        onClick={toggle}
-        style={{
-          marginLeft: 4,
-          padding: "2px 8px",
-          border: "1px solid #7c3aed",
-          borderRadius: 4,
-          color: "#7c3aed",
-          background: "transparent",
-          cursor: "pointer",
-          fontSize: 12,
-        }}
-      >
-        {open ? "Show less ▲" : "Show more ▼"}
-      </button>
-    ),
-  },
-}
+      {/* Custom button text */}
+      <div>
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md mb-4 font-medium">
+          Custom Button Text
+        </h4>
+        <div className="space-y-2">
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            readMoreText / readLessText overrides
+          </p>
+          <ClampLines
+            wordLimit={25}
+            readMoreText="Continue reading →"
+            readLessText="← Show less"
+          >
+            {EPISODE_DESC}
+          </ClampLines>
+        </div>
+      </div>
 
-export const WithOnToggle: Story = {
-  name: "With onToggle (Toast)",
-  args: {
-    children: LONG_TEXT,
-    wordLimit: 20,
-    onToggle: (open) => {
-      toast(open ? "Expanded" : "Collapsed", {
-        description: open
-          ? "Full text is now visible."
-          : "Text has been collapsed.",
-      })
+      {/* Custom render button */}
+      <div>
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md mb-4 font-medium">
+          Custom Render Button
+        </h4>
+        <div className="space-y-2">
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            Fully custom button via the button render-prop
+          </p>
+          <ClampLines
+            wordLimit={25}
+            button={(open, toggle) => (
+              <Button
+                variant="outline"
+                size="sm"
+                onClick={toggle}
+                className="ml-1 h-fit"
+                innerClassName="px-2 py-0.5"
+              >
+                {open ? "Show less ▲" : "Show more ▼"}
+              </Button>
+            )}
+          >
+            {EPISODE_DESC}
+          </ClampLines>
+        </div>
+      </div>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Comparison of all configuration axes: word-count limits, CSS line-clamp mode, responsive scaling, custom button labels, and a custom render-prop button.",
+      },
     },
   },
-  decorators: [
-    (Story) => (
-      <>
-        <Story />
-        <Toaster />
-      </>
-    ),
-  ],
 }
 
-export const ShortText: Story = {
-  name: "Short Text (no truncation)",
-  args: {
-    children: "This text is short enough that it will never be truncated.",
-    wordLimit: 20,
-  },
-}
+// ─── 2. Interactive ──────────────────────────────────────────────────────────
 
-export const AllVariants = () => {
-  return (
-    <div className="flex flex-col gap-6" style={{ width: 400 }}>
-      <div>
-        <p className="text-fm-tertiary text-fm-xs mb-2 uppercase">
-          Word Limit (20 words)
-        </p>
-        <ClampLines wordLimit={20}>{LONG_TEXT}</ClampLines>
-      </div>
-      <div>
-        <p className="text-fm-tertiary text-fm-xs mb-2 uppercase">
-          CSS Line Clamp (3 lines)
-        </p>
-        <ClampLines>{LONG_TEXT}</ClampLines>
-      </div>
-      <div>
-        <p className="text-fm-tertiary text-fm-xs mb-2 uppercase">
-          Responsive (40 words, min 10)
-        </p>
-        <ClampLines wordLimit={40} responsive minWordLimit={10}>
-          {LONG_TEXT}
-        </ClampLines>
+export const Interactive: Story = {
+  render: () => {
+    const [isOpen, setIsOpen] = useState(false)
+    const [toggleCount, setToggleCount] = useState(0)
+
+    const handleToggle = (open: boolean) => {
+      setIsOpen(open)
+      setToggleCount((c) => c + 1)
+    }
+
+    return (
+      <div className="w-full p-8">
+        <div className="mx-auto max-w-3xl space-y-6">
+          <div className="grid grid-cols-1 gap-6 lg:grid-cols-3">
+            {/* Controls panel */}
+            <div className="border-fm-divider-secondary bg-fm-surface-secondary space-y-5 rounded-xl border p-5">
+              <p className="text-fm-primary font-fm-brand text-fm-sm leading-fm-sm font-semibold tracking-widest uppercase">
+                Live State
+              </p>
+
+              <div className="space-y-3">
+                <div className="border-fm-divider-secondary rounded-lg border px-4 py-3">
+                  <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                    Expanded
+                  </p>
+                  <p className="text-fm-primary font-fm-brand text-fm-md leading-fm-md font-semibold">
+                    {isOpen ? "Yes" : "No"}
+                  </p>
+                </div>
+
+                <div className="border-fm-divider-secondary rounded-lg border px-4 py-3">
+                  <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                    Toggle count
+                  </p>
+                  <p className="text-fm-primary font-fm-brand text-fm-md leading-fm-md font-semibold">
+                    {toggleCount}
+                  </p>
+                </div>
+              </div>
+
+              <div className="border-fm-divider-secondary border-t pt-4" />
+
+              <div className="space-y-2">
+                <p className="text-fm-primary font-fm-brand text-fm-sm leading-fm-sm font-semibold tracking-widest uppercase">
+                  About
+                </p>
+                <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-4">
+                  <p className="text-fm-secondary font-fm-text text-fm-md leading-fm-xl">
+                    The <code className="font-(--font-fm-mono)">onToggle</code>{" "}
+                    callback fires every time the user clicks the
+                    expand/collapse button. Use it to track analytics, update
+                    parent state, or trigger side-effects.
+                  </p>
+                </div>
+              </div>
+            </div>
+
+            {/* Preview stage */}
+            <div className="flex flex-col gap-3 lg:col-span-2">
+              <div
+                className="border-fm-divider-secondary bg-fm-surface-secondary rounded-xl border p-6"
+                style={{ minHeight: 180 }}
+              >
+                <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm mb-3">
+                  Episode description — click READ MORE / READ LESS
+                </p>
+                <ClampLines wordLimit={30} onToggle={handleToggle}>
+                  {EPISODE_DESC}
+                </ClampLines>
+              </div>
+
+              <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)">
+                  {`<ClampLines wordLimit={30} onToggle={(open) => setIsOpen(open)}>`}
+                  <br />
+                  {`  {episodeDescription}`}
+                  <br />
+                  {`</ClampLines>`}
+                </code>
+              </div>
+            </div>
+          </div>
+        </div>
       </div>
-    </div>
-  )
+    )
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Live expand/collapse demo wired to a local state tracker via the onToggle callback. The left panel reflects current open state and cumulative toggle count in real time.",
+      },
+    },
+  },
 }