@particle-academy/react-fancy 5.29.1 → 5.30.0

package/dist/Card-CuRZivBz.d.cts

@@ -0,0 +1,136 @@
+import * as react from 'react';
+import { HTMLAttributes, ReactNode } from 'react';
+
+/** Scales the card's padding and its corner radius. */
+type CardSize = "xs" | "sm" | "md" | "lg";
+/**
+ * The inset applied to the card's direct children.
+ *
+ * Separate from `CardSize` because they are separate keys: `size` only picks
+ * the DEFAULT step, and `padding` overrides it. Anything that has to line up
+ * with the content's edge — an inset divider, a `Card.Bleed` — is keyed by this
+ * and never by `size`.
+ */
+type CardPadding = "none" | "xs" | "sm" | "md" | "lg";
+/**
+ * How `Card.Header` / `Card.Body` / `Card.Footer` are set apart.
+ *
+ * `"divided"` is the default because it is what Card has always rendered.
+ * Seamless is arguably the nicer default — it is what Flux chose — but making
+ * it the default here would have silently restyled every card in every
+ * consumer, which is not a thing a minor release may do.
+ */
+type CardSections = "divided" | "plain" | "banded";
+/** Which of the card's edges a `Card.Bleed` reaches. */
+type CardBleedEdges = "x" | "top" | "bottom" | "all";
+interface CardProps extends HTMLAttributes<HTMLDivElement> {
+    /**
+     * The card's surface. `muted` and `soft` are tint steps between `outlined`
+     * (no tint) and `flat`.
+     */
+    variant?: "outlined" | "elevated" | "flat" | "muted" | "soft";
+    /**
+     * Padding on the card's direct children. Defaults to the step implied by
+     * `size`; pass it to override that, including `"none"`.
+     */
+    padding?: CardPadding;
+    /** Scales padding and corner radius together. Default `"md"`. */
+    size?: CardSize;
+    /** How the header, body and footer are separated. Default `"divided"`. */
+    sections?: CardSections;
+    /**
+     * With `sections="divided"`, stop the rules at the content's edge instead of
+     * running them across the card.
+     */
+    dividerInset?: boolean;
+    /**
+     * A faint hairline along the inside of the top edge — white at 70% in light
+     * mode, white at 10% in dark, so a tinted or elevated surface reads as lit
+     * from above in both.
+     *
+     * Default `false`, deliberately unlike Flux's `true` — flipping a decorative
+     * hairline on by default would change the appearance of every existing card.
+     */
+    highlight?: boolean;
+    /**
+     * Card is a link or a grid tile: adds the hover lift + border/shadow
+     * response, and clips children to the rounded corners so a `Card.Media`
+     * sits flush.
+     */
+    interactive?: boolean;
+}
+interface CardMediaProps extends HTMLAttributes<HTMLDivElement> {
+    /** Image URL. Omit for a pure colour/gradient tile. */
+    src?: string;
+    alt?: string;
+    /** CSS `aspect-ratio`. Default `"16/9"`. Ignored when `height` is set. */
+    ratio?: string;
+    /** Fixed height instead of an aspect ratio. */
+    height?: number | string;
+    /**
+     * Shown UNDER the image — while it loads, and permanently if it never
+     * arrives. Any CSS background value, so a gradient works.
+     */
+    background?: string;
+    /** `object-position` for the image. Default `"center"`. */
+    objectPosition?: string;
+    loading?: "lazy" | "eager";
+    /** Slots pinned to the media's corners — a number chip, a status pill. */
+    topLeft?: ReactNode;
+    topRight?: ReactNode;
+    bottomLeft?: ReactNode;
+    bottomRight?: ReactNode;
+}
+/**
+ * Shared by `Card.Header` and `Card.Footer`.
+ *
+ * `heading` / `description` / `actions` exist so the common header does not
+ * need a layout wrapper from the caller. Two pages in this suite's own showcase
+ * were writing `<div style={{ display: "flex", justifyContent: "space-between"
+ * }}>` INSIDE a `Card.Header` — inline styles, in the app whose job is to
+ * demonstrate the kit. 136 headers there, and nothing in the kit laid one out.
+ *
+ * `children` is the escape hatch and it WINS: pass it and the three props are
+ * ignored rather than rendered alongside, so a caller who sets both gets one
+ * title instead of two.
+ */
+interface CardSectionProps extends HTMLAttributes<HTMLDivElement> {
+    /** The title. Rendered through `<Heading>`. */
+    heading?: ReactNode;
+    /** Which heading element to render. Default `"h3"`. */
+    headingLevel?: "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
+    /** Supporting line under the heading. Rendered through muted `<Text>`. */
+    description?: ReactNode;
+    /** Controls pushed to the far end, vertically centred on the heading. */
+    actions?: ReactNode;
+    /**
+     * Only used when there is no `Card` above this — a standalone header takes
+     * its own size, because there is no card to inherit one from.
+     */
+    size?: CardSize;
+    /** Full control. Replaces heading/description/actions, keeps the frame. */
+    children?: ReactNode;
+}
+interface CardHeaderProps extends CardSectionProps {
+}
+interface CardFooterProps extends CardSectionProps {
+}
+interface CardBodyProps extends HTMLAttributes<HTMLDivElement> {
+}
+interface CardBleedProps extends HTMLAttributes<HTMLDivElement> {
+    /**
+     * Which card edges to reach. Default `"x"` — the sides only, which is what
+     * an inline image or table wants.
+     */
+    edges?: CardBleedEdges;
+}
+
+declare const Card: react.ForwardRefExoticComponent<CardProps & react.RefAttributes<HTMLDivElement>> & {
+    Media: react.ForwardRefExoticComponent<CardMediaProps & react.RefAttributes<HTMLDivElement>>;
+    Header: react.ForwardRefExoticComponent<CardHeaderProps & react.RefAttributes<HTMLDivElement>>;
+    Body: react.ForwardRefExoticComponent<CardBodyProps & react.RefAttributes<HTMLDivElement>>;
+    Footer: react.ForwardRefExoticComponent<CardFooterProps & react.RefAttributes<HTMLDivElement>>;
+    Bleed: react.ForwardRefExoticComponent<CardBleedProps & react.RefAttributes<HTMLDivElement>>;
+};
+
+export { type CardHeaderProps as C, type CardBodyProps as a, type CardFooterProps as b, type CardMediaProps as c, type CardBleedProps as d, Card as e, type CardBleedEdges as f, type CardPadding as g, type CardProps as h, type CardSectionProps as i, type CardSections as j, type CardSize as k };

package/dist/Card-CuRZivBz.d.ts

@@ -0,0 +1,136 @@
+import * as react from 'react';
+import { HTMLAttributes, ReactNode } from 'react';
+
+/** Scales the card's padding and its corner radius. */
+type CardSize = "xs" | "sm" | "md" | "lg";
+/**
+ * The inset applied to the card's direct children.
+ *
+ * Separate from `CardSize` because they are separate keys: `size` only picks
+ * the DEFAULT step, and `padding` overrides it. Anything that has to line up
+ * with the content's edge — an inset divider, a `Card.Bleed` — is keyed by this
+ * and never by `size`.
+ */
+type CardPadding = "none" | "xs" | "sm" | "md" | "lg";
+/**
+ * How `Card.Header` / `Card.Body` / `Card.Footer` are set apart.
+ *
+ * `"divided"` is the default because it is what Card has always rendered.
+ * Seamless is arguably the nicer default — it is what Flux chose — but making
+ * it the default here would have silently restyled every card in every
+ * consumer, which is not a thing a minor release may do.
+ */
+type CardSections = "divided" | "plain" | "banded";
+/** Which of the card's edges a `Card.Bleed` reaches. */
+type CardBleedEdges = "x" | "top" | "bottom" | "all";
+interface CardProps extends HTMLAttributes<HTMLDivElement> {
+    /**
+     * The card's surface. `muted` and `soft` are tint steps between `outlined`
+     * (no tint) and `flat`.
+     */
+    variant?: "outlined" | "elevated" | "flat" | "muted" | "soft";
+    /**
+     * Padding on the card's direct children. Defaults to the step implied by
+     * `size`; pass it to override that, including `"none"`.
+     */
+    padding?: CardPadding;
+    /** Scales padding and corner radius together. Default `"md"`. */
+    size?: CardSize;
+    /** How the header, body and footer are separated. Default `"divided"`. */
+    sections?: CardSections;
+    /**
+     * With `sections="divided"`, stop the rules at the content's edge instead of
+     * running them across the card.
+     */
+    dividerInset?: boolean;
+    /**
+     * A faint hairline along the inside of the top edge — white at 70% in light
+     * mode, white at 10% in dark, so a tinted or elevated surface reads as lit
+     * from above in both.
+     *
+     * Default `false`, deliberately unlike Flux's `true` — flipping a decorative
+     * hairline on by default would change the appearance of every existing card.
+     */
+    highlight?: boolean;
+    /**
+     * Card is a link or a grid tile: adds the hover lift + border/shadow
+     * response, and clips children to the rounded corners so a `Card.Media`
+     * sits flush.
+     */
+    interactive?: boolean;
+}
+interface CardMediaProps extends HTMLAttributes<HTMLDivElement> {
+    /** Image URL. Omit for a pure colour/gradient tile. */
+    src?: string;
+    alt?: string;
+    /** CSS `aspect-ratio`. Default `"16/9"`. Ignored when `height` is set. */
+    ratio?: string;
+    /** Fixed height instead of an aspect ratio. */
+    height?: number | string;
+    /**
+     * Shown UNDER the image — while it loads, and permanently if it never
+     * arrives. Any CSS background value, so a gradient works.
+     */
+    background?: string;
+    /** `object-position` for the image. Default `"center"`. */
+    objectPosition?: string;
+    loading?: "lazy" | "eager";
+    /** Slots pinned to the media's corners — a number chip, a status pill. */
+    topLeft?: ReactNode;
+    topRight?: ReactNode;
+    bottomLeft?: ReactNode;
+    bottomRight?: ReactNode;
+}
+/**
+ * Shared by `Card.Header` and `Card.Footer`.
+ *
+ * `heading` / `description` / `actions` exist so the common header does not
+ * need a layout wrapper from the caller. Two pages in this suite's own showcase
+ * were writing `<div style={{ display: "flex", justifyContent: "space-between"
+ * }}>` INSIDE a `Card.Header` — inline styles, in the app whose job is to
+ * demonstrate the kit. 136 headers there, and nothing in the kit laid one out.
+ *
+ * `children` is the escape hatch and it WINS: pass it and the three props are
+ * ignored rather than rendered alongside, so a caller who sets both gets one
+ * title instead of two.
+ */
+interface CardSectionProps extends HTMLAttributes<HTMLDivElement> {
+    /** The title. Rendered through `<Heading>`. */
+    heading?: ReactNode;
+    /** Which heading element to render. Default `"h3"`. */
+    headingLevel?: "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
+    /** Supporting line under the heading. Rendered through muted `<Text>`. */
+    description?: ReactNode;
+    /** Controls pushed to the far end, vertically centred on the heading. */
+    actions?: ReactNode;
+    /**
+     * Only used when there is no `Card` above this — a standalone header takes
+     * its own size, because there is no card to inherit one from.
+     */
+    size?: CardSize;
+    /** Full control. Replaces heading/description/actions, keeps the frame. */
+    children?: ReactNode;
+}
+interface CardHeaderProps extends CardSectionProps {
+}
+interface CardFooterProps extends CardSectionProps {
+}
+interface CardBodyProps extends HTMLAttributes<HTMLDivElement> {
+}
+interface CardBleedProps extends HTMLAttributes<HTMLDivElement> {
+    /**
+     * Which card edges to reach. Default `"x"` — the sides only, which is what
+     * an inline image or table wants.
+     */
+    edges?: CardBleedEdges;
+}
+
+declare const Card: react.ForwardRefExoticComponent<CardProps & react.RefAttributes<HTMLDivElement>> & {
+    Media: react.ForwardRefExoticComponent<CardMediaProps & react.RefAttributes<HTMLDivElement>>;
+    Header: react.ForwardRefExoticComponent<CardHeaderProps & react.RefAttributes<HTMLDivElement>>;
+    Body: react.ForwardRefExoticComponent<CardBodyProps & react.RefAttributes<HTMLDivElement>>;
+    Footer: react.ForwardRefExoticComponent<CardFooterProps & react.RefAttributes<HTMLDivElement>>;
+    Bleed: react.ForwardRefExoticComponent<CardBleedProps & react.RefAttributes<HTMLDivElement>>;
+};
+
+export { type CardHeaderProps as C, type CardBodyProps as a, type CardFooterProps as b, type CardMediaProps as c, type CardBleedProps as d, Card as e, type CardBleedEdges as f, type CardPadding as g, type CardProps as h, type CardSectionProps as i, type CardSections as j, type CardSize as k };

package/dist/card.cjs

@@ -1,29 +1,35 @@
 'use strict';
 
-var chunk5DQ2XUJI_cjs = require('./chunk-5DQ2XUJI.cjs');
+var chunk5F6V5HHT_cjs = require('./chunk-5F6V5HHT.cjs');
+require('./chunk-XLFGWNW4.cjs');
+require('./chunk-65HKNZFG.cjs');
 require('./chunk-ZU5Q77OT.cjs');
 
 
 
 Object.defineProperty(exports, "Card", {
   enumerable: true,
-  get: function () { return chunk5DQ2XUJI_cjs.Card; }
+  get: function () { return chunk5F6V5HHT_cjs.Card; }
+});
+Object.defineProperty(exports, "CardBleed", {
+  enumerable: true,
+  get: function () { return chunk5F6V5HHT_cjs.CardBleed; }
 });
 Object.defineProperty(exports, "CardBody", {
   enumerable: true,
-  get: function () { return chunk5DQ2XUJI_cjs.CardBody; }
+  get: function () { return chunk5F6V5HHT_cjs.CardBody; }
 });
 Object.defineProperty(exports, "CardFooter", {
   enumerable: true,
-  get: function () { return chunk5DQ2XUJI_cjs.CardFooter; }
+  get: function () { return chunk5F6V5HHT_cjs.CardFooter; }
 });
 Object.defineProperty(exports, "CardHeader", {
   enumerable: true,
-  get: function () { return chunk5DQ2XUJI_cjs.CardHeader; }
+  get: function () { return chunk5F6V5HHT_cjs.CardHeader; }
 });
 Object.defineProperty(exports, "CardMedia", {
   enumerable: true,
-  get: function () { return chunk5DQ2XUJI_cjs.CardMedia; }
+  get: function () { return chunk5F6V5HHT_cjs.CardMedia; }
 });
 //# sourceMappingURL=card.cjs.map
 //# sourceMappingURL=card.cjs.map

package/dist/card.d.cts

@@ -1,11 +1,20 @@
-import { C as CardHeaderProps, a as CardBodyProps, b as CardFooterProps, c as CardMediaProps } from './Card-BZ5F6-wd.cjs';
-export { d as Card, e as CardProps } from './Card-BZ5F6-wd.cjs';
+import { C as CardHeaderProps, a as CardBodyProps, b as CardFooterProps, c as CardMediaProps, d as CardBleedProps } from './Card-CuRZivBz.cjs';
+export { e as Card, f as CardBleedEdges, g as CardPadding, h as CardProps, i as CardSectionProps, j as CardSections, k as CardSize } from './Card-CuRZivBz.cjs';
 import * as react from 'react';
 
+/**
+ * A card's header. Also usable on its own, as a section heading above a card —
+ * see `CardSection`, which decides that from the absence of a `CardContext`.
+ */
 declare const CardHeader: react.ForwardRefExoticComponent<CardHeaderProps & react.RefAttributes<HTMLDivElement>>;
 
 declare const CardBody: react.ForwardRefExoticComponent<CardBodyProps & react.RefAttributes<HTMLDivElement>>;
 
+/**
+ * A card's footer. Its rule sits on the TOP edge, and a lone `actions` block
+ * aligns to the end — matching `ModalFooter`, which has always done that while
+ * this component laid out nothing.
+ */
 declare const CardFooter: react.ForwardRefExoticComponent<CardFooterProps & react.RefAttributes<HTMLDivElement>>;
 
 /**
@@ -26,4 +35,42 @@ declare const CardFooter: react.ForwardRefExoticComponent<CardFooterProps & reac
  */
 declare const CardMedia: react.ForwardRefExoticComponent<CardMediaProps & react.RefAttributes<HTMLDivElement>>;
 
-export { CardBody, CardBodyProps, CardFooter, CardFooterProps, CardHeader, CardHeaderProps, CardMedia, CardMediaProps };
+/**
+ * Run content out to the card's edges — an image, a table, a chart strip.
+ *
+ * ## Why this is arithmetic and not a CSS-variable protocol
+ *
+ * Flux solves the same problem with a published set of custom properties
+ * (`--flux-bleed-x`, `--flux-bleed-top`, …) that any child component may read.
+ * It has to: its padding sits on the CARD, so a descendant has no way to know
+ * how far it must reach. That is a public CSS API — a cross-package contract to
+ * version forever.
+ *
+ * Ours does not need one, because padding sits on the card's direct CHILDREN.
+ * The distance to the edge is therefore always one padding step, which the
+ * padded section passes down in context. No variables, nothing for a consumer
+ * to depend on, nothing to keep stable across releases.
+ *
+ * ## Two cases, and they are opposites
+ *
+ * - **Inside a `Card.Header` / `Card.Body` / `Card.Footer`** (the normal case):
+ *   the padding is on that section, so reaching the edge is a NEGATIVE MARGIN.
+ * - **As a direct child of `Card`**: the padding is on this element, so
+ *   reaching the edge is ZEROING it. A negative margin here would pull the
+ *   content clean outside the card.
+ *
+ * A component cannot see its own depth, so the sections publish their padding
+ * step in context and its absence means "you are the padded element". Both
+ * cases read as "cancel the padding", which is exactly why picking either one
+ * alone ships looking correct in whichever demo the author happened to write.
+ *
+ * The distance comes from that context and NOT from the card's `size`, because
+ * the two disagree whenever `padding` is passed explicitly — and disagree by a
+ * whole step, which looks like a rendering bug rather than a prop conflict.
+ *
+ * Corners are rounded only where the content actually meets the card's edge, so
+ * a mid-body strip stays square while one at the top follows the card's radius.
+ */
+declare const CardBleed: react.ForwardRefExoticComponent<CardBleedProps & react.RefAttributes<HTMLDivElement>>;
+
+export { CardBleed, CardBleedProps, CardBody, CardBodyProps, CardFooter, CardFooterProps, CardHeader, CardHeaderProps, CardMedia, CardMediaProps };

package/dist/card.d.ts

@@ -1,11 +1,20 @@
-import { C as CardHeaderProps, a as CardBodyProps, b as CardFooterProps, c as CardMediaProps } from './Card-BZ5F6-wd.js';
-export { d as Card, e as CardProps } from './Card-BZ5F6-wd.js';
+import { C as CardHeaderProps, a as CardBodyProps, b as CardFooterProps, c as CardMediaProps, d as CardBleedProps } from './Card-CuRZivBz.js';
+export { e as Card, f as CardBleedEdges, g as CardPadding, h as CardProps, i as CardSectionProps, j as CardSections, k as CardSize } from './Card-CuRZivBz.js';
 import * as react from 'react';
 
+/**
+ * A card's header. Also usable on its own, as a section heading above a card —
+ * see `CardSection`, which decides that from the absence of a `CardContext`.
+ */
 declare const CardHeader: react.ForwardRefExoticComponent<CardHeaderProps & react.RefAttributes<HTMLDivElement>>;
 
 declare const CardBody: react.ForwardRefExoticComponent<CardBodyProps & react.RefAttributes<HTMLDivElement>>;
 
+/**
+ * A card's footer. Its rule sits on the TOP edge, and a lone `actions` block
+ * aligns to the end — matching `ModalFooter`, which has always done that while
+ * this component laid out nothing.
+ */
 declare const CardFooter: react.ForwardRefExoticComponent<CardFooterProps & react.RefAttributes<HTMLDivElement>>;
 
 /**
@@ -26,4 +35,42 @@ declare const CardFooter: react.ForwardRefExoticComponent<CardFooterProps & reac
  */
 declare const CardMedia: react.ForwardRefExoticComponent<CardMediaProps & react.RefAttributes<HTMLDivElement>>;
 
-export { CardBody, CardBodyProps, CardFooter, CardFooterProps, CardHeader, CardHeaderProps, CardMedia, CardMediaProps };
+/**
+ * Run content out to the card's edges — an image, a table, a chart strip.
+ *
+ * ## Why this is arithmetic and not a CSS-variable protocol
+ *
+ * Flux solves the same problem with a published set of custom properties
+ * (`--flux-bleed-x`, `--flux-bleed-top`, …) that any child component may read.
+ * It has to: its padding sits on the CARD, so a descendant has no way to know
+ * how far it must reach. That is a public CSS API — a cross-package contract to
+ * version forever.
+ *
+ * Ours does not need one, because padding sits on the card's direct CHILDREN.
+ * The distance to the edge is therefore always one padding step, which the
+ * padded section passes down in context. No variables, nothing for a consumer
+ * to depend on, nothing to keep stable across releases.
+ *
+ * ## Two cases, and they are opposites
+ *
+ * - **Inside a `Card.Header` / `Card.Body` / `Card.Footer`** (the normal case):
+ *   the padding is on that section, so reaching the edge is a NEGATIVE MARGIN.
+ * - **As a direct child of `Card`**: the padding is on this element, so
+ *   reaching the edge is ZEROING it. A negative margin here would pull the
+ *   content clean outside the card.
+ *
+ * A component cannot see its own depth, so the sections publish their padding
+ * step in context and its absence means "you are the padded element". Both
+ * cases read as "cancel the padding", which is exactly why picking either one
+ * alone ships looking correct in whichever demo the author happened to write.
+ *
+ * The distance comes from that context and NOT from the card's `size`, because
+ * the two disagree whenever `padding` is passed explicitly — and disagree by a
+ * whole step, which looks like a rendering bug rather than a prop conflict.
+ *
+ * Corners are rounded only where the content actually meets the card's edge, so
+ * a mid-body strip stays square while one at the top follows the card's radius.
+ */
+declare const CardBleed: react.ForwardRefExoticComponent<CardBleedProps & react.RefAttributes<HTMLDivElement>>;
+
+export { CardBleed, CardBleedProps, CardBody, CardBodyProps, CardFooter, CardFooterProps, CardHeader, CardHeaderProps, CardMedia, CardMediaProps };

package/dist/card.js

@@ -1,4 +1,6 @@
-export { Card, CardBody, CardFooter, CardHeader, CardMedia } from './chunk-ZIDBI6JX.js';
+export { Card, CardBleed, CardBody, CardFooter, CardHeader, CardMedia } from './chunk-CF2U25LM.js';
+import './chunk-5RLP77KK.js';
+import './chunk-CESGP5AF.js';
 import './chunk-MMW2JGKZ.js';
 //# sourceMappingURL=card.js.map
 //# sourceMappingURL=card.js.map