@fpkit/acss 0.6.2 → 1.0.0

package/src/components/heading/README.mdx

@@ -0,0 +1,292 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="FP.REACT Components/Heading (Deprecated)/Readme" />
+
+# Heading (Deprecated)
+
+> ⚠️ **DEPRECATED**: This component is deprecated and will be removed in **v3.0.0**. Please use the [`Title`](?path=/docs/fp-react-components-title--docs) component instead.
+
+---
+
+## Deprecation Notice
+
+<div style={{ padding: '1.5rem', background: '#fef3c7', border: '2px solid #f59e0b', borderRadius: '0.5rem', marginBottom: '2rem' }}>
+  <strong style={{ color: '#92400e', fontSize: '1.125rem' }}>⚠️ This component is deprecated</strong>
+  <p style={{ marginTop: '0.5rem', color: '#78350f' }}>
+    The <code>Heading</code> component has been replaced by the new <code>Title</code> component
+    which offers improved API design, better accessibility features, and enhanced performance.
+  </p>
+  <p style={{ marginTop: '0.5rem', color: '#78350f' }}>
+    <strong>Removal Timeline:</strong> This component will be removed in v3.0.0 (TBD)
+  </p>
+</div>
+
+---
+
+## Quick Migration
+
+### Before (Deprecated)
+
+```tsx
+import { Heading } from '@fpkit/acss';
+
+<Heading type="h2">Section Title</Heading>
+```
+
+### After (Recommended)
+
+```tsx
+import { Title } from '@fpkit/acss';
+
+<Title level="h2">Section Title</Title>
+```
+
+---
+
+## Why We Deprecated Heading
+
+The new `Title` component provides several advantages over the deprecated `Heading` component:
+
+<div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(250px, 1fr))', gap: '1rem', margin: '1.5rem 0' }}>
+  <div style={{ padding: '1rem', border: '1px solid #e0e0e0', borderRadius: '0.5rem' }}>
+    <strong>✅ Better API</strong>
+    <p style={{ fontSize: '0.875rem', color: '#666' }}>The <code>level</code> prop is more semantic and descriptive than <code>type</code></p>
+  </div>
+  <div style={{ padding: '1rem', border: '1px solid #e0e0e0', borderRadius: '0.5rem' }}>
+    <strong>✅ Improved Accessibility</strong>
+    <p style={{ fontSize: '0.875rem', color: '#666' }}>Enhanced WCAG 2.1 AA compliance with better screen reader support</p>
+  </div>
+  <div style={{ padding: '1rem', border: '1px solid #e0e0e0', borderRadius: '0.5rem' }}>
+    <strong>✅ Better Documentation</strong>
+    <p style={{ fontSize: '0.875rem', color: '#666' }}>Comprehensive JSDoc comments for improved TypeScript IntelliSense</p>
+  </div>
+  <div style={{ padding: '1rem', border: '1px solid #e0e0e0', borderRadius: '0.5rem' }}>
+    <strong>✅ Performance</strong>
+    <p style={{ fontSize: '0.875rem', color: '#666' }}>React.memo optimization prevents unnecessary re-renders</p>
+  </div>
+</div>
+
+---
+
+## Migration Guide
+
+### Step-by-Step Migration
+
+#### 1. Update Imports
+
+```tsx
+// Before
+import { Heading } from '@fpkit/acss';
+
+// After
+import { Title } from '@fpkit/acss';
+```
+
+#### 2. Rename the Component
+
+```tsx
+// Before
+<Heading type="h2">Section Title</Heading>
+
+// After
+<Title level="h2">Section Title</Title>
+```
+
+#### 3. Update the Prop Name
+
+The only prop that changed is `type` → `level`:
+
+| Old Prop | New Prop | Description |
+|----------|----------|-------------|
+| `type` | `level` | The semantic heading level (h1-h6) |
+
+#### 4. Review Default Behavior
+
+**IMPORTANT:** The default heading level changed:
+
+- **Heading (old)**: Default is `h3`
+- **Title (new)**: Default is `h2`
+
+If you relied on the default, you may need to explicitly specify `h3`:
+
+```tsx
+// Before (implicitly h3)
+<Heading>Default Heading</Heading>
+
+// After (explicitly h3 to maintain behavior)
+<Title level="h3">Default Heading</Title>
+
+// Or use the new default (h2)
+<Title>Default Title</Title>
+```
+
+---
+
+## All Heading Levels
+
+The `Heading` component supports all six semantic heading levels, just like `Title`:
+
+```tsx
+// h1 - Page title (use once per page)
+<Heading type="h1">Main Page Title</Heading>
+
+// h2 - Major sections
+<Heading type="h2">Section Heading</Heading>
+
+// h3 - Subsections (default)
+<Heading type="h3">Subsection Heading</Heading>
+
+// h4-h6 - Deeper nesting
+<Heading type="h4">Level Four Heading</Heading>
+<Heading type="h5">Level Five Heading</Heading>
+<Heading type="h6">Level Six Heading</Heading>
+```
+
+**Migrate to:**
+
+```tsx
+// h1 - Page title (use once per page)
+<Title level="h1">Main Page Title</Title>
+
+// h2 - Major sections (now default)
+<Title level="h2">Section Heading</Title>
+
+// h3 - Subsections
+<Title level="h3">Subsection Heading</Title>
+
+// h4-h6 - Deeper nesting
+<Title level="h4">Level Four Heading</Title>
+<Title level="h5">Level Five Heading</Title>
+<Title level="h6">Level Six Heading</Title>
+```
+
+---
+
+## Props
+
+> **Note**: These props still work but are deprecated. Refer to the [Title component documentation](?path=/docs/fp-react-components-title--docs) for the current API.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `type` | `"h1" \| "h2" \| "h3" \| "h4" \| "h5" \| "h6"` | `"h3"` | **Deprecated.** Use `level` on Title component instead |
+| `children` | `React.ReactNode` | *required* | The content to display in the heading |
+| `ui` | `string` | - | Data attribute for fpkit styling hooks |
+| `className` | `string` | - | CSS class names to apply |
+| `ref` | `React.Ref<HTMLHeadingElement>` | - | Forwarded ref to the heading element |
+
+All other standard HTML heading attributes and ARIA properties are also supported.
+
+---
+
+## Current Behavior
+
+The `Heading` component still works for backwards compatibility but:
+
+### Development Warnings
+
+In development mode, the component logs deprecation warnings to the console:
+
+```
+[@fpkit/acss] Heading component is deprecated and will be removed in v3.0.0.
+Please use the Title component instead.
+Migration: <Heading type="h2"> → <Title level="h2">
+See documentation: https://fpkit.dev/components/title
+```
+
+### Production Behavior
+
+- No console warnings in production builds
+- Full backwards compatibility maintained
+- All props forwarded correctly to Title component
+- Performance identical to direct Title usage
+
+---
+
+## TypeScript Support
+
+The component maintains full TypeScript support:
+
+```tsx
+import { Heading, type TitleProps } from '@fpkit/acss';
+
+// Old API (still typed correctly)
+<Heading type="h2">Typed Heading</Heading>
+
+// Type-safe with all Title props
+const props: TitleProps = {
+  type: 'h3',
+  children: 'Section Title',
+  className: 'custom-class'
+};
+<Heading {...props} />
+```
+
+However, TypeScript will show deprecation warnings in your IDE for better migration visibility.
+
+---
+
+## Migration Checklist
+
+Use this checklist to ensure a smooth migration:
+
+- [ ] Find all `<Heading>` imports in your codebase
+- [ ] Replace `import { Heading }` with `import { Title }`
+- [ ] Replace all `<Heading>` tags with `<Title>`
+- [ ] Replace all `type` props with `level`
+- [ ] Review uses without explicit `type` prop (default changed from `h3` → `h2`)
+- [ ] Test all migrated components
+- [ ] Remove any `Heading` imports
+- [ ] Search for any remaining references to `Heading` component
+
+### Find and Replace Tips
+
+**VS Code / IDE Search:**
+
+```regex
+# Find
+<Heading\s+type="(h[1-6])"
+
+# Replace with
+<Title level="$1"
+```
+
+**Command Line (ripgrep):**
+
+```bash
+# Find all Heading usage
+rg "Heading" --type tsx --type ts
+
+# Find Heading imports
+rg "import.*Heading.*from.*@fpkit/acss"
+```
+
+---
+
+## Related Components
+
+- **[Title](?path=/docs/fp-react-components-title--docs)** - The recommended replacement component
+- **Text** - For body text and paragraphs
+
+---
+
+## Support & Resources
+
+- **Title Component Docs**: [View documentation](?path=/docs/fp-react-components-title--docs)
+- **GitHub**: [fpkit/acss](https://github.com/fpkit/acss)
+- **Migration Help**: Open an issue if you need assistance migrating
+
+---
+
+<div style={{ padding: '1.5rem', background: '#f0f9ff', border: '1px solid #0ea5e9', borderRadius: '0.5rem', marginTop: '2rem' }}>
+  <strong>💡 Migration Tip:</strong> The Title component maintains the same functionality
+  while providing better DX and accessibility. The migration is straightforward and can be done incrementally.
+  Start by migrating new code, then gradually update existing components.
+</div>
+
+<div style={{ padding: '1.5rem', background: '#fef3c7', border: '2px solid #f59e0b', borderRadius: '0.5rem', marginTop: '1rem' }}>
+  <strong style={{ color: '#92400e' }}>⚠️ Removal Timeline</strong>
+  <p style={{ marginTop: '0.5rem', color: '#78350f', marginBottom: 0 }}>
+    Plan to complete your migration before upgrading to v3.0.0.
+    This component will be completely removed in that release.
+  </p>
+</div>

package/src/components/icons/icon.stories.tsx

@@ -9,7 +9,7 @@ import "./icon.scss";
 const meta: Meta<typeof Icon> = {
   component: Icon,
   title: "FP.React Components/Icons",
-  tags: ["rc"],
+  tags: ["stable"],
   args: {
     // styles: Icon.styles,
   },

package/src/components/images/figure.stories.tsx

@@ -11,7 +11,47 @@ const meta: Meta<typeof Figure> = {
     actions: { argTypesRegex: "^on.*" },
     docs: {
       description: {
-        component: "Figure description here...",
+        component: `A semantic figure component for displaying images with captions, using CSS custom properties for flexible styling.
+
+## CSS Variables
+
+Customize the Figure and Image appearance using CSS custom properties:
+
+### Image Variables (img[alt])
+- \`--img-max-width\`: Maximum width (default: \`100%\`)
+- \`--img-height\`: Height value (default: \`auto\`)
+- \`--img-display\`: Display type (default: \`inline-block\`)
+- \`--img-object-fit\`: Object fit mode (default: \`cover\`)
+- \`--img-object-position\`: Object position (default: \`center\`)
+- \`--img-aspect-ratio\`: Aspect ratio (default: \`auto 2/3\`)
+
+### Figure Variables (figure:has(img[alt]))
+- \`--fig-display\`: Display type (default: \`flex\`)
+- \`--fig-padding\`: Figure padding (default: \`0.5rem\`)
+- \`--fig-bg\`: Background color (default: \`rgba(245, 245, 245, 0.683)\`)
+- \`--fig-width\`: Max width constraint (default: \`fit-content\`)
+- \`--fig-bottom\`: Figcaption bottom offset (default: \`var(--fig-padding)\`)
+- \`--fig-left\`: Figcaption left offset (default: \`var(--fig-padding)\`)
+- \`--fig-right\`: Figcaption right offset (default: \`var(--fig-padding)\`)
+
+### Figcaption Variables
+- \`--caption-padding\`: Caption padding (default: \`var(--spc-3)\`)
+
+**Example:**
+\`\`\`css
+figure:has(img[alt]) {
+  --fig-padding: 1rem;
+  --fig-bg: #f5f5f5;
+  --fig-width: 40rem;
+  --caption-padding: 1.5rem;
+}
+
+img[alt] {
+  --img-max-width: 100%;
+  --img-object-fit: contain;
+  --img-aspect-ratio: 16/9;
+}
+\`\`\``,
       },
     },
   },

package/src/components/images/img.scss

@@ -39,20 +39,20 @@ img[alt] {
 figure {
   &:has(img[alt]) {
     --fig-display: flex;
-    --fig-p: 0.5rem;
+    --fig-padding: 0.5rem;
     --fig-bg: rgba(245, 245, 245, 0.683);
-    --fig-w: fit-content;
+    --fig-width: fit-content;
     display: var(--fig-display);
     position: relative;
-    padding: var(--fig-p);
+    padding: var(--fig-padding);
     background-color: var(--fig-bg);
-    max-width: var(--fig-w);
+    max-width: var(--fig-width);
     > figcaption {
       position: absolute;
-      bottom: var(--fig-bottom, var(--fig-p));
-      left: var(--fig-left, var(--fig-p));
-      right: var(--fig-right, var(--fig-p));
-      padding: var(--caption-p, var(--spc-3));
+      bottom: var(--fig-bottom, var(--fig-padding));
+      left: var(--fig-left, var(--fig-padding));
+      right: var(--fig-right, var(--fig-padding));
+      padding: var(--caption-padding, var(--spc-3));
       background-color: var(--fig-bg);
     }
   }

package/src/components/images/img.scss.backup

@@ -0,0 +1,59 @@
+/**
+ * Image component styles
+ *
+ * Applies to all images with alt attribute (both decorative alt="" and semantic).
+ * Uses CSS custom properties for flexible theming and responsive behavior.
+ */
+img[alt] {
+  /* CSS Custom Properties - Override these for customization */
+  --img-max-width: 100%;
+  --img-height: auto;
+  --img-object-fit: cover;
+  --img-object-position: center;
+  --img-aspect-ratio: auto 2/3;
+  --img-display: inline-block;
+
+  /* Layout - Responsive by default */
+  max-width: var(--img-max-width);
+  max-inline-size: var(--img-max-width); /* Logical property for i18n */
+  block-size: var(--img-height);
+  display: var(--img-display);
+  vertical-align: middle;
+
+  /* Object fitting for responsive images */
+  object-fit: var(--img-object-fit);
+  object-position: var(--img-object-position);
+  aspect-ratio: var(--img-aspect-ratio);
+
+  /* Accessibility - Italic font for broken image alt text */
+  font-style: italic;
+
+  /* Background for loading state */
+  background-size: cover;
+  background-repeat: no-repeat;
+
+  /* Shape margin for text wrapping */
+  shape-margin: var(--spc-3);
+}
+
+figure {
+  &:has(img[alt]) {
+    --fig-display: flex;
+    --fig-p: 0.5rem;
+    --fig-bg: rgba(245, 245, 245, 0.683);
+    --fig-w: fit-content;
+    display: var(--fig-display);
+    position: relative;
+    padding: var(--fig-p);
+    background-color: var(--fig-bg);
+    max-width: var(--fig-w);
+    > figcaption {
+      position: absolute;
+      bottom: var(--fig-bottom, var(--fig-p));
+      left: var(--fig-left, var(--fig-p));
+      right: var(--fig-right, var(--fig-p));
+      padding: var(--caption-p, var(--spc-3));
+      background-color: var(--fig-bg);
+    }
+  }
+}

package/src/components/layout/_header.scss

@@ -9,24 +9,24 @@ header,
   --overlay-display: grid;
   // Overlay padding
   --overlay-padding: 2rem;
-  --overlay-w: 100%;
-  --overlay-h: 40vh;
-  --overlay-max-h: 500px;
+  --overlay-width: 100%;
+  --overlay-height: 40vh;
+  --overlay-max-height: 500px;
   --overlay-color: currentColor;
-  --overlay-content-w: 80%;
+  --overlay-content-width: 80%;
   --overlay-gap: 2rem;
   --overlay-bg: whitesmoke;
-  --overlay-px: auto;
-  --overlay-py: auto;
-  --overlay-mx: auto;
-  --overlay-my: auto;
+  --overlay-padding-inline: auto;
+  --overlay-padding-block: auto;
+  --overlay-margin-inline: auto;
+  --overlay-margin-block: auto;
 
   grid-template-areas: 'overlay';
   display: var(--overlay-display);
   place-items: var(--overlay-placement);
   align-items: var(--overlay-placement);
-  min-height: var(--overlay-h);
-  width: var(--overlay-w);
+  min-height: var(--overlay-height);
+  width: var(--overlay-width);
   color: var(--overlay-color);
   background-color: var(--overlay-bg);
   min-width: 20rem;
@@ -34,16 +34,16 @@ header,
     grid-area: overlay;
   }
   > img {
-    width: var(--overlay-w);
+    width: var(--overlay-width);
     // height: auto;
     background-size: contain;
   }
   > div,
   > section {
     --overlay-display: flex;
-    max-width: var(--overlay-content-w);
+    max-width: var(--overlay-content-width);
     padding-inline: var(--spc-4);
-    margin-inline: var(--overlay-mx);
+    margin-inline: var(--overlay-margin-inline);
     gap: var(--overlay-gap);
     text-align: center;
     p {
@@ -54,7 +54,7 @@ header,
     }
     > h1,
     > h2 {
-      line-height: var(--header-lh, 1.1);
+      line-height: var(--header-line-height, 1.1);
       font-weight: 500;
     }
 

package/src/components/layout/_header.scss.backup

@@ -0,0 +1,72 @@
+header,
+[data-hero],
+[data-grid~='overlay'] {
+  // Name of the grid area
+  --overlay-grid-area: overlay;
+  // Placement of items in grid area
+  --overlay-placement: center;
+  // Controls display of grid
+  --overlay-display: grid;
+  // Overlay padding
+  --overlay-padding: 2rem;
+  --overlay-w: 100%;
+  --overlay-h: 40vh;
+  --overlay-max-h: 500px;
+  --overlay-color: currentColor;
+  --overlay-content-w: 80%;
+  --overlay-gap: 2rem;
+  --overlay-bg: whitesmoke;
+  --overlay-px: auto;
+  --overlay-py: auto;
+  --overlay-mx: auto;
+  --overlay-my: auto;
+
+  grid-template-areas: 'overlay';
+  display: var(--overlay-display);
+  place-items: var(--overlay-placement);
+  align-items: var(--overlay-placement);
+  min-height: var(--overlay-h);
+  width: var(--overlay-w);
+  color: var(--overlay-color);
+  background-color: var(--overlay-bg);
+  min-width: 20rem;
+  > * {
+    grid-area: overlay;
+  }
+  > img {
+    width: var(--overlay-w);
+    // height: auto;
+    background-size: contain;
+  }
+  > div,
+  > section {
+    --overlay-display: flex;
+    max-width: var(--overlay-content-w);
+    padding-inline: var(--spc-4);
+    margin-inline: var(--overlay-mx);
+    gap: var(--overlay-gap);
+    text-align: center;
+    p {
+      width: auto;
+      max-width: 60ch;
+      font-size: var(--fs-8);
+      line-height: 1.4;
+    }
+    > h1,
+    > h2 {
+      line-height: var(--header-lh, 1.1);
+      font-weight: 500;
+    }
+
+    > h1 {
+      font-size: var(--fs-12);
+    }
+    > h2 {
+      font-size: var(--fs-11);
+    }
+    > h3 {
+      font-size: var(--fs-10);
+    }
+
+  }
+}

package/src/components/layout/landmarks.scss

@@ -3,14 +3,14 @@
 
 main,
 footer {
-  --content-w: min(100%, 1480px);
-  --content-mx: auto;
-  --content-px: 1rem;
+  --content-width: min(100%, 1480px);
+  --content-margin-inline: auto;
+  --content-padding-inline: 1rem;
   --content-gap: 2rem;
   padding-block: var(--overlay-padding);
   > section {
-    width: var(--content-w);
-    margin-inline: var(--content-mx);
+    width: var(--content-width);
+    margin-inline: var(--content-margin-inline);
     padding-inline: var(--spc-6);
   }
 }
@@ -20,8 +20,8 @@ main {
   font-size: var(--fs-3);
   > section[aria-label],
   > section {
-    width: var(--content-w);
-    margin-inline: var(--content-mx);
+    width: var(--content-width);
+    margin-inline: var(--content-margin-inline);
     &:has(> article, > aside) {
       display: flex;
       flex-wrap: wrap;

package/src/components/layout/landmarks.scss.backup

@@ -0,0 +1,51 @@
+@use './header';
+
+
+main,
+footer {
+  --content-w: min(100%, 1480px);
+  --content-mx: auto;
+  --content-px: 1rem;
+  --content-gap: 2rem;
+  padding-block: var(--overlay-padding);
+  > section {
+    width: var(--content-w);
+    margin-inline: var(--content-mx);
+    padding-inline: var(--spc-6);
+  }
+}
+
+main {
+  flex: 1;
+  font-size: var(--fs-3);
+  > section[aria-label],
+  > section {
+    width: var(--content-w);
+    margin-inline: var(--content-mx);
+    &:has(> article, > aside) {
+      display: flex;
+      flex-wrap: wrap;
+      flex: 1;
+      gap: var(--content-gap);
+      > article {
+        flex-basis: 0;
+        flex-grow: 999;
+        min-inline-size: 50%;
+      }
+      > aside {
+        flex-basis: 20rem;
+        flex-grow: 1;
+      }
+    }
+  }
+}
+
+footer {
+  > div {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    min-height: 5rem;
+    text-align: center;
+  }
+}