@pithyjs/ui-kit 0.1.0-beta.0

package/dist/layout/SmartContainer.js

@@ -0,0 +1,194 @@
+/** @codex
+{
+  "id": "pithy.ui-kit.smart-container",
+  "title": "<SmartContainer> Layout Component",
+  "category": "feature"
+}
+*/
+import { renderChildren } from '@pithyjs/core';
+import { captureSlot } from '../shared/slots';
+import { GAP_CLASS, ALIGN_CLASS, JUSTIFY_CLASS, CSS_LENGTH_PATTERN, } from '../shared/common';
+import { GRID_COLS_CLASS, RESPONSIVE_GRID_COLS } from '../shared/grid';
+import { RECIPE_ITEMS, DENSITY_ITEMS, DENSITY_RATIO, } from '../shared/smart-container';
+import { applyElementDensity } from '@pithyjs/design-system';
+function clampLanes(n) {
+    if (!Number.isFinite(n))
+        return 3;
+    return Math.max(2, Math.min(6, Math.round(n)));
+}
+/**
+ * Build classes for the equal-cards recipe based on lanes count.
+ * Maps lane count to responsive grid column breakpoint classes.
+ */
+function buildLaneClasses(lanes) {
+    const classes = [GRID_COLS_CLASS[1]]; // base: 1 column
+    if (lanes >= 2)
+        classes.push(RESPONSIVE_GRID_COLS.sm[2]);
+    if (lanes >= 3)
+        classes.push(RESPONSIVE_GRID_COLS.md[3]);
+    // For lanes=6 use lg:5 to avoid a 4→6 jump at xl
+    if (lanes >= 4 && lanes <= 5)
+        classes.push(RESPONSIVE_GRID_COLS.lg[4]);
+    if (lanes === 6)
+        classes.push(RESPONSIVE_GRID_COLS.lg[5]);
+    if (lanes >= 5)
+        classes.push(RESPONSIVE_GRID_COLS.xl[Math.min(lanes, 6)]);
+    return classes;
+}
+/**
+ * Higher-level layout component providing 5 opinionated responsive
+ * layout recipes that adapt to container width via CSS container queries.
+ *
+ * Unlike Grid/Stack (low-level primitives), SmartContainer provides
+ * common layout patterns that "just work" responsively.
+ *
+ * @example
+ * ```html
+ * <!-- Auto-grid: items flow into columns based on minimum width -->
+ * <SmartContainer recipe="'auto-grid'" minItem="'14rem'" gap="'lg'">
+ *   <div>Card 1</div>
+ *   <div>Card 2</div>
+ *   <div>Card 3</div>
+ * </SmartContainer>
+ *
+ * <!-- Stack-to-row: vertical on mobile, horizontal on wider containers -->
+ * <SmartContainer recipe="'stack-to-row'">
+ *   <div>Left</div>
+ *   <div>Right</div>
+ * </SmartContainer>
+ *
+ * <!-- Equal cards: responsive grid capped at N columns -->
+ * <SmartContainer recipe="'equal-cards'" lanes="4">
+ *   <div>Card 1</div>
+ *   <div>Card 2</div>
+ *   <div>Card 3</div>
+ *   <div>Card 4</div>
+ * </SmartContainer>
+ * ```
+ */
+/** @codexApi {"parent":"pithy.ui-kit.smart-container","name":"SmartContainer","stability":"stable","signature":"(props?: SmartContainerProps) => { el: HTMLElement | DocumentFragment; destroy: () => void }"} */
+export function SmartContainer({ recipe: rawRecipe = 'auto-grid', minItem = undefined, gap: rawGap = 'md', density: rawDensity = 'normal', align: rawAlign = undefined, justify: rawJustify = undefined, lanes: rawLanes = 3, as = 'div', } = {}) {
+    // Validate and fall back unconditionally (not just DEV) to prevent undefined class names in production
+    const hasOwn = Object.prototype.hasOwnProperty;
+    const validRecipe = RECIPE_ITEMS.includes(rawRecipe);
+    const validGap = hasOwn.call(GAP_CLASS, rawGap);
+    const validDensity = DENSITY_ITEMS.includes(rawDensity);
+    const validAlign = rawAlign == null || hasOwn.call(ALIGN_CLASS, rawAlign);
+    const validJustify = rawJustify == null || hasOwn.call(JUSTIFY_CLASS, rawJustify);
+    if (import.meta.env?.DEV) {
+        if (!validRecipe) {
+            const valid = RECIPE_ITEMS.join(', ');
+            console.warn(`[<SmartContainer>] Invalid recipe value: "${rawRecipe}". Expected one of: ${valid}. Falling back to "auto-grid".`);
+        }
+        if (!validGap) {
+            const valid = Object.keys(GAP_CLASS).join(', ');
+            console.warn(`[<SmartContainer>] Invalid gap value: "${rawGap}". Expected one of: ${valid}. Falling back to "md".`);
+        }
+        if (!validDensity) {
+            const valid = DENSITY_ITEMS.join(', ');
+            console.warn(`[<SmartContainer>] Invalid density value: "${rawDensity}". Expected one of: ${valid}. Falling back to "normal".`);
+        }
+        if (!validAlign) {
+            const valid = Object.keys(ALIGN_CLASS).join(', ');
+            console.warn(`[<SmartContainer>] Invalid align value: "${rawAlign}". Expected one of: ${valid}. Ignoring.`);
+        }
+        if (!validJustify) {
+            const valid = Object.keys(JUSTIFY_CLASS).join(', ');
+            console.warn(`[<SmartContainer>] Invalid justify value: "${rawJustify}". Expected one of: ${valid}. Ignoring.`);
+        }
+        if (rawRecipe !== 'equal-cards' && rawLanes !== 3) {
+            console.warn(`[<SmartContainer>] lanes prop is only used with the "equal-cards" recipe. Ignoring.`);
+        }
+        if (rawRecipe !== 'auto-grid' && minItem != null) {
+            console.warn(`[<SmartContainer>] minItem prop is only used with the "auto-grid" recipe. Ignoring.`);
+        }
+        if ((rawRecipe === 'auto-grid' || !validRecipe) &&
+            minItem != null &&
+            !CSS_LENGTH_PATTERN.test(minItem)) {
+            console.warn(`[<SmartContainer>] Suspicious minItem value: "${minItem}". Expected a CSS length (e.g. "250px", "14rem"). Note: fr units are not valid inside minmax().`);
+        }
+    }
+    const recipe = validRecipe ? rawRecipe : 'auto-grid';
+    const gap = validGap ? rawGap : 'md';
+    const density = validDensity ? rawDensity : 'normal';
+    const align = validAlign ? rawAlign : undefined;
+    const justify = validJustify ? rawJustify : undefined;
+    const lanes = clampLanes(rawLanes);
+    // Common classes for all recipes
+    const gapClass = GAP_CLASS[gap];
+    const alignClass = align ? ALIGN_CLASS[align] : '';
+    const justifyClass = justify ? JUSTIFY_CLASS[justify] : '';
+    // Build recipe-specific inner classes
+    let innerClasses;
+    switch (recipe) {
+        case 'auto-grid':
+            innerClasses = [
+                'u-grid',
+                'u-grid-auto-fit',
+                gapClass,
+                alignClass,
+                justifyClass,
+            ];
+            break;
+        case 'stack-to-row':
+            innerClasses = ['u-sc-stack-to-row', gapClass, alignClass, justifyClass];
+            break;
+        case 'row-wrap':
+            innerClasses = [
+                'u-flex',
+                'u-flex-wrap',
+                gapClass,
+                alignClass,
+                justifyClass,
+            ];
+            break;
+        case 'sidebar':
+            innerClasses = ['u-sc-sidebar', gapClass, alignClass, justifyClass];
+            break;
+        case 'equal-cards':
+            innerClasses = [
+                'u-grid',
+                ...buildLaneClasses(lanes),
+                ...(align ? [] : ['u-items-stretch']),
+                gapClass,
+                alignClass,
+                justifyClass,
+            ];
+            break;
+    }
+    // Add child control class for grid-based recipes
+    if (recipe === 'auto-grid' ||
+        recipe === 'sidebar' ||
+        recipe === 'equal-cards') {
+        innerClasses.push('u-sc-child-span');
+    }
+    // Add collapse control class for all recipes
+    innerClasses.push('u-sc-child-collapse');
+    // Filter empty strings
+    innerClasses = innerClasses.filter(Boolean);
+    // Compile children through full pipeline
+    const { el: childFragment, destroy } = renderChildren();
+    // Double-nesting: outer = container-type, inner = recipe layout
+    const outer = document.createElement(as);
+    outer.classList.add('u-container-inline');
+    const inner = document.createElement('div');
+    for (const cls of innerClasses)
+        inner.classList.add(cls);
+    // Set CSS variables
+    if (recipe === 'auto-grid' && minItem) {
+        inner.style.setProperty('--grid-auto-min', minItem);
+    }
+    applyElementDensity(outer, DENSITY_RATIO[density]);
+    captureSlot(inner, 'default');
+    inner.appendChild(childFragment);
+    outer.appendChild(inner);
+    return {
+        el: outer,
+        destroy: () => {
+            destroy();
+            inner.replaceChildren();
+            outer.replaceChildren();
+        },
+    };
+}
+//# sourceMappingURL=SmartContainer.js.map

package/dist/layout/SmartContainer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SmartContainer.js","sourceRoot":"","sources":["../../src/layout/SmartContainer.ts"],"names":[],"mappings":"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"}

package/dist/layout/Stack.d.ts

@@ -0,0 +1,65 @@
+/** @codex
+{
+  "id": "pithy.ui-kit.stack",
+  "title": "<Stack> Layout Component",
+  "category": "feature"
+}
+*/
+import { type AlignItems } from '../shared/common';
+import { type Orientation } from '../shared/types';
+import type { SpacingSize } from '@pithyjs/design-system';
+/** @codexApi {"parent":"pithy.ui-kit.stack","name":"StackProps","stability":"stable","signature":"interface StackProps"} */
+export interface StackProps {
+    /** Stack direction (default: "vertical") */
+    direction?: Orientation;
+    /** Gap between children — maps to u-gap-* utilities (default: "md") */
+    gap?: SpacingSize;
+    /** Cross-axis alignment — maps to u-items-* utilities (default: "stretch") */
+    align?: AlignItems;
+    /** Whether children wrap to next line (default: false) */
+    wrap?: boolean;
+    /** Reverse the stacking order (default: false) */
+    reverse?: boolean;
+    /**
+     * Minimum child width before wrapping (CSS length, e.g. "200px", "15rem").
+     * When set on a horizontal stack, enables fluid responsive behavior:
+     * children will wrap to a new row when they can't maintain this minimum
+     * width. Automatically enables `wrap`. (default: undefined — no fluid behavior)
+     */
+    minChildWidth?: string;
+    /** HTML tag to render (default: "div") */
+    as?: keyof HTMLElementTagNameMap;
+}
+/**
+ * Layout atom that arranges children in a vertical or horizontal stack.
+ *
+ * Maps props to design-system utility classes (u-vstack, u-hstack,
+ * u-gap-*, u-items-*, u-flex-wrap, u-flex-col-reverse, u-flex-row-reverse).
+ * No custom CSS required.
+ *
+ * For fluid responsive horizontal layouts, set `minChildWidth` — children
+ * will wrap to a new row when they can't maintain the minimum width.
+ * This uses pure CSS flex-wrap, no breakpoints or container queries.
+ *
+ * @example
+ * ```html
+ * <!-- Simple stack -->
+ * <Stack direction="'horizontal'" gap="'lg'" align="'center'">
+ *   <div>Item 1</div>
+ *   <div>Item 2</div>
+ * </Stack>
+ *
+ * <!-- Fluid responsive: wraps to vertical when children < 200px -->
+ * <Stack direction="'horizontal'" gap="'md'" minChildWidth="'200px'">
+ *   <div>Item 1</div>
+ *   <div>Item 2</div>
+ *   <div>Item 3</div>
+ * </Stack>
+ * ```
+ */
+/** @codexApi {"parent":"pithy.ui-kit.stack","name":"Stack","stability":"stable","signature":"(props?: StackProps) => { el: HTMLElement | DocumentFragment; destroy: () => void }"} */
+export declare function Stack({ direction: rawDirection, gap: rawGap, align: rawAlign, wrap, reverse, minChildWidth, as, }?: StackProps): {
+    el: HTMLElement | DocumentFragment;
+    destroy: () => void;
+};
+//# sourceMappingURL=Stack.d.ts.map

package/dist/layout/Stack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Stack.d.ts","sourceRoot":"","sources":["../../src/layout/Stack.ts"],"names":[],"mappings":"AAAA;;;;;;EAME;AAGF,OAAO,EAIL,KAAK,UAAU,EAChB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAgB,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAI1D,4HAA4H;AAC5H,MAAM,WAAW,UAAU;IACzB,4CAA4C;IAC5C,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,uEAAuE;IACvE,GAAG,CAAC,EAAE,WAAW,CAAC;IAClB,8EAA8E;IAC9E,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,0DAA0D;IAC1D,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,kDAAkD;IAClD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,0CAA0C;IAC1C,EAAE,CAAC,EAAE,MAAM,qBAAqB,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,sLAAsL;AACtL,wBAAgB,KAAK,CAAC,EACpB,SAAS,EAAE,YAAyB,EACpC,GAAG,EAAE,MAAa,EAClB,KAAK,EAAE,QAAoB,EAC3B,IAAY,EACZ,OAAe,EACf,aAAyB,EACzB,EAAU,GACX,GAAE,UAAe,GAAG;IACnB,EAAE,EAAE,WAAW,GAAG,gBAAgB,CAAC;IACnC,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB,CA6FA"}

package/dist/layout/Stack.js

@@ -0,0 +1,114 @@
+/** @codex
+{
+  "id": "pithy.ui-kit.stack",
+  "title": "<Stack> Layout Component",
+  "category": "feature"
+}
+*/
+import { renderChildren } from '@pithyjs/core';
+import { GAP_CLASS, ALIGN_CLASS, CSS_LENGTH_PATTERN, } from '../shared/common';
+import { captureSlot } from '../shared/slots';
+import { ORIENTATIONS } from '../shared/types';
+let fluidStackUid = 0;
+/**
+ * Layout atom that arranges children in a vertical or horizontal stack.
+ *
+ * Maps props to design-system utility classes (u-vstack, u-hstack,
+ * u-gap-*, u-items-*, u-flex-wrap, u-flex-col-reverse, u-flex-row-reverse).
+ * No custom CSS required.
+ *
+ * For fluid responsive horizontal layouts, set `minChildWidth` — children
+ * will wrap to a new row when they can't maintain the minimum width.
+ * This uses pure CSS flex-wrap, no breakpoints or container queries.
+ *
+ * @example
+ * ```html
+ * <!-- Simple stack -->
+ * <Stack direction="'horizontal'" gap="'lg'" align="'center'">
+ *   <div>Item 1</div>
+ *   <div>Item 2</div>
+ * </Stack>
+ *
+ * <!-- Fluid responsive: wraps to vertical when children < 200px -->
+ * <Stack direction="'horizontal'" gap="'md'" minChildWidth="'200px'">
+ *   <div>Item 1</div>
+ *   <div>Item 2</div>
+ *   <div>Item 3</div>
+ * </Stack>
+ * ```
+ */
+/** @codexApi {"parent":"pithy.ui-kit.stack","name":"Stack","stability":"stable","signature":"(props?: StackProps) => { el: HTMLElement | DocumentFragment; destroy: () => void }"} */
+export function Stack({ direction: rawDirection = 'vertical', gap: rawGap = 'md', align: rawAlign = 'stretch', wrap = false, reverse = false, minChildWidth = undefined, as = 'div', } = {}) {
+    const hasOwn = Object.prototype.hasOwnProperty;
+    const validGap = hasOwn.call(GAP_CLASS, rawGap);
+    const validAlign = hasOwn.call(ALIGN_CLASS, rawAlign);
+    const validDirection = ORIENTATIONS.includes(rawDirection);
+    if (import.meta.env?.DEV) {
+        if (!validGap) {
+            const valid = Object.keys(GAP_CLASS).join(', ');
+            console.warn(`[<Stack>] Invalid gap value: "${rawGap}". Expected one of: ${valid}. Falling back to "md".`);
+        }
+        if (!validAlign) {
+            const valid = Object.keys(ALIGN_CLASS).join(', ');
+            console.warn(`[<Stack>] Invalid align value: "${rawAlign}". Expected one of: ${valid}. Falling back to "stretch".`);
+        }
+        if (!validDirection) {
+            const valid = ORIENTATIONS.join(', ');
+            console.warn(`[<Stack>] Invalid direction value: "${rawDirection}". Expected one of: ${valid}. Falling back to "vertical".`);
+        }
+        if (minChildWidth != null && !CSS_LENGTH_PATTERN.test(minChildWidth)) {
+            console.warn(`[<Stack>] Suspicious minChildWidth value: "${minChildWidth}". Expected a CSS length (e.g. "200px", "15rem").`);
+        }
+        if (minChildWidth != null && rawDirection !== 'horizontal') {
+            console.warn(`[<Stack>] minChildWidth is only supported on horizontal stacks and will be ignored.`);
+        }
+    }
+    const direction = validDirection ? rawDirection : 'vertical';
+    const gap = validGap ? rawGap : 'md';
+    const align = validAlign ? rawAlign : 'stretch';
+    // minChildWidth implies wrap for horizontal stacks
+    const shouldWrap = wrap || (minChildWidth != null && direction === 'horizontal');
+    const classes = [
+        'u-flex',
+        reverse
+            ? direction === 'horizontal'
+                ? 'u-flex-row-reverse'
+                : 'u-flex-col-reverse'
+            : direction === 'horizontal'
+                ? 'u-hstack'
+                : 'u-vstack',
+        GAP_CLASS[gap],
+        ALIGN_CLASS[align],
+        shouldWrap ? 'u-flex-wrap' : '',
+    ].filter(Boolean);
+    // Create wrapper element with utility classes
+    const wrapper = document.createElement(as);
+    for (const cls of classes)
+        wrapper.classList.add(cls);
+    // Fluid mode: use a scoped <style> with `> *` rule so ALL direct children
+    // (including those added later by structural directives) get the flex sizing.
+    // flex: 1 0 <min> ensures children won't shrink below minChildWidth and will
+    // wrap to a new row instead (matching the prop's documented contract).
+    if (minChildWidth != null && direction === 'horizontal') {
+        // Validate against CSS injection — reject values that don't match a safe CSS length pattern
+        const trimmed = minChildWidth.trim();
+        const safeValue = CSS_LENGTH_PATTERN.test(trimmed) ? trimmed : '0px';
+        const scopeAttr = `data-stack-fluid-${fluidStackUid++}`;
+        wrapper.setAttribute(scopeAttr, '');
+        const styleEl = document.createElement('style');
+        styleEl.textContent = `[${scopeAttr}] > :not(style) { flex: 1 0 ${safeValue}; min-inline-size: ${safeValue}; }`;
+        wrapper.appendChild(styleEl);
+    }
+    captureSlot(wrapper, 'default');
+    // Compile children through full pipeline (enables nested <Stack>)
+    const { el: childFragment, destroy } = renderChildren();
+    wrapper.appendChild(childFragment);
+    return {
+        el: wrapper,
+        destroy: () => {
+            destroy();
+            wrapper.replaceChildren();
+        },
+    };
+}
+//# sourceMappingURL=Stack.js.map

package/dist/layout/Stack.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Stack.js","sourceRoot":"","sources":["../../src/layout/Stack.ts"],"names":[],"mappings":"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"}

package/dist/organisms/content/Card.d.ts

@@ -0,0 +1,93 @@
+/** @codex
+{
+  "id": "pithy.ui-kit.card",
+  "title": "<Card> Organism",
+  "category": "feature",
+  "risk": "medium"
+}
+*/
+import { type Orientation } from '../../shared/types';
+import { type CardVariant, type CardPadding, type CardRadius, type CardMediaAspect } from '../../shared/card';
+/** @codexApi {"parent":"pithy.ui-kit.card","name":"CardProps","stability":"stable","signature":"interface CardProps"} */
+export interface CardProps {
+    /** Visual variant (default: "default") */
+    variant?: CardVariant;
+    /** Inset padding (default: "md"). "none" bleeds media to the card edges. */
+    padding?: CardPadding;
+    /** Corner radius (default: "md") */
+    radius?: CardRadius;
+    /** Layout direction (default: "vertical"). "horizontal" places media at the inline-start. */
+    orientation?: Orientation;
+    /**
+     * Aspect ratio for the `media` slot. Optional in vertical mode (defaults to
+     * the media's intrinsic ratio). In horizontal mode it defaults to "16/9" so
+     * thumbnails stay rhythmically consistent across list layouts.
+     */
+    mediaAspect?: CardMediaAspect;
+    /**
+     * Full-bleed media overlay mode. The media slot fills the whole card
+     * (ignoring `padding`) and the header / body / footer stack at the
+     * block-end on top of a gradient scrim with inverse text colors. Canonical
+     * pattern for hero tiles, gallery cards, and marketing listings where the
+     * image carries the eye and the caption is secondary.
+     */
+    mediaOverlay?: boolean;
+    /** Make the whole card a navigation target via a stretched pseudo-link overlay. */
+    clickable?: boolean;
+    /** Href for the clickable overlay (validated via isSafeHref). Required when `clickable`. */
+    href?: string;
+    /** Screen-reader label for the clickable overlay. Defaults to `ariaLabel` or the card's heading. */
+    linkLabel?: string;
+    /**
+     * Disable interactivity. Applies `aria-disabled` + `inert` + dimmed chrome.
+     * Accepts a boolean or a reactive getter (`() => boolean`) — when a getter
+     * is passed, Card wires an internal effect that tracks it.
+     */
+    disabled?: boolean | (() => boolean);
+    /**
+     * Mark the card as selected. Sets `aria-current="true"` (when clickable) +
+     * primary-tinted chrome. Accepts a boolean or a reactive getter
+     * (`() => boolean`) — when a getter is passed, Card wires an internal effect
+     * so the card repaints without remounting.
+     */
+    selected?: boolean | (() => boolean);
+    /**
+     * Short uppercase label rendered above the heading in the header slot —
+     * primary-colored, letter-spaced, semibold. Mirrors the `eyebrow` prop on
+     * Hero / CTA sections. Used for category tags ("Engineering", "Product")
+     * and editorial kickers. Auto-injected into the header slot when set.
+     */
+    eyebrow?: string;
+    /** Fallback accessible name for the article (used when no heading is present in the header slot). */
+    ariaLabel?: string;
+    /** Explicit id of an element labeling this card (takes precedence over auto-detection). */
+    ariaLabelledBy?: string;
+    /** Anchor id on the `<article>` root. */
+    id?: string;
+}
+/**
+ * Content container with named slots (`media`, `header`, default = body,
+ * `footer`), five variants, orientation, and a pseudo-link pattern that
+ * lets the whole card act as a navigation target without sacrificing
+ * interactive children.
+ *
+ * @example
+ * ```html
+ * <Card variant="'elevated'" clickable="true" href="'/post/hello'">
+ *   <img data-slot="media" src="/hero.jpg" alt="">
+ *   <header data-slot="header">
+ *     <Heading level="3">Hello world</Heading>
+ *   </header>
+ *   <Text>A short excerpt…</Text>
+ *   <footer data-slot="footer">
+ *     <Text color="'text-muted'" size="'sm'">3 min read</Text>
+ *   </footer>
+ * </Card>
+ * ```
+ */
+/** @codexApi {"parent":"pithy.ui-kit.card","name":"Card","stability":"stable","signature":"(props?: CardProps) => { el: HTMLElement; destroy: () => void }"} */
+export declare function Card(props?: CardProps): {
+    el: HTMLElement;
+    destroy: () => void;
+};
+//# sourceMappingURL=Card.d.ts.map

package/dist/organisms/content/Card.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Card.d.ts","sourceRoot":"","sources":["../../../src/organisms/content/Card.ts"],"names":[],"mappings":"AAAA;;;;;;;EAOE;AAQF,OAAO,EAAgB,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACpE,OAAO,EAKL,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,eAAe,EACrB,MAAM,mBAAmB,CAAC;AAI3B,yHAAyH;AACzH,MAAM,WAAW,SAAS;IACxB,0CAA0C;IAC1C,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,oCAAoC;IACpC,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,6FAA6F;IAC7F,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;;;OAIG;IACH,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,mFAAmF;IACnF,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,4FAA4F;IAC5F,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oGAAoG;IACpG,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,GAAG,CAAC,MAAM,OAAO,CAAC,CAAC;IACrC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,GAAG,CAAC,MAAM,OAAO,CAAC,CAAC;IACrC;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qGAAqG;IACrG,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2FAA2F;IAC3F,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,yCAAyC;IACzC,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AA2CD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,gKAAgK;AAChK,wBAAgB,IAAI,CAAC,KAAK,GAAE,SAAc,GAAG;IAC3C,EAAE,EAAE,WAAW,CAAC;IAChB,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB,CA0WA"}