@mohasinac/appkit 2.8.9 → 3.0.0

package/dist/ui/components/Semantic.d.ts

@@ -18,16 +18,16 @@ import type { SurfaceProps } from "./surface-tokens";
  * import { Section, Article, Main, Aside, Nav, Ul, Ol, Li } from '..';
  *
  * <Main className="max-w-7xl mx-auto px-4">
- *   <Section className="py-12">
- *     <Article>...</Article>
- *   </Section>
- *   <Aside className="w-64 shrink-0">...</Aside>
+ * <Section className="py-12">
+ * <Article>...</Article>
+ * </Section>
+ * <Aside className="w-64 shrink-0">...</Aside>
  * </Main>
  *
  * <Nav aria-label="Main navigation">
- *   <Ul className="flex gap-4">
- *     <Li>Products</Li>
- *   </Ul>
+ * <Ul className="flex gap-4">
+ * <Li>Products</Li>
+ * </Ul>
  * </Nav>
  * ```
  */
@@ -36,7 +36,33 @@ import type { SurfaceProps } from "./surface-tokens";
  * Use for thematically grouped content that would appear in an outline.
  * Prefer this over a plain `<div data-section="semantic-div-596">` when the block has a heading.
  */
+/**
+ * Themed gradient tones for Section. Each tone resolves to a
+ * `--appkit-gradient-*` CSS variable so admin custom themes restyle the
+ * section without consumer changes.
+ */
+export type SectionTone = "plain" | "page-header" | "hero" | "accent-banner";
+type SemanticColor = "default" | "primary" | "muted" | "faint" | "inverse" | "success" | "warning" | "error" | "info";
+type SectionLayout = "default" | "flex" | "flex-col" | "flex-sm-row" | "flex-sm-row-between";
+type SectionGap = "none" | "xs" | "sm" | "md" | "lg";
+type SectionAlign = "start" | "center" | "end" | "stretch" | "baseline";
+type SectionJustify = "start" | "center" | "end" | "between" | "around" | "evenly";
 export interface SectionProps extends React.HTMLAttributes<HTMLElement>, SurfaceProps {
+    /**
+     * Themed background tone. Defaults to `"plain"`. Use `"page-header"` for
+     * subtle gradient page-headers, `"hero"` for radial mesh hero backgrounds,
+     * `"accent-banner"` for primary→secondary brand banners.
+     */
+    tone?: SectionTone;
+    color?: SemanticColor;
+    /** Layout preset. `flex-sm-row` is the canonical "mobile column, sm+ row" pattern. */
+    layout?: SectionLayout;
+    /** Gap between flex/grid children. Only takes effect when `layout` is set. */
+    gap?: SectionGap;
+    /** Cross-axis alignment. Only takes effect when `layout` is set. */
+    align?: SectionAlign;
+    /** Main-axis justification. Only takes effect when `layout` is set. */
+    justify?: SectionJustify;
     children: React.ReactNode;
 }
 export declare const Section: React.ForwardRefExoticComponent<SectionProps & React.RefAttributes<HTMLElement>>;
@@ -45,23 +71,26 @@ export declare const Section: React.ForwardRefExoticComponent<SectionProps & Rea
  * Use for self-contained compositions: blog posts, product cards, reviews, forum posts.
  */
 export interface ArticleProps extends React.HTMLAttributes<HTMLElement>, SurfaceProps {
+    color?: SemanticColor;
     children?: React.ReactNode;
 }
-export declare function Article({ className, surface, padding, rounded, border, shadow, children, ...props }: ArticleProps): import("react/jsx-runtime").JSX.Element;
+export declare function Article({ className, surface, padding, rounded, border, shadow, color, children, ...props }: ArticleProps): import("react/jsx-runtime").JSX.Element;
 /**
  * Semantic `<main>` element.
  * Wraps the primary content of the document. Should appear only once per page.
  */
 export interface MainProps extends React.HTMLAttributes<HTMLElement>, SurfaceProps {
+    color?: SemanticColor;
     children: React.ReactNode;
 }
-export declare function Main({ className, surface, padding, rounded, border, shadow, children, ...props }: MainProps): import("react/jsx-runtime").JSX.Element;
+export declare function Main({ className, surface, padding, paddingX, paddingY, rounded, border, shadow, color, children, ...props }: MainProps): import("react/jsx-runtime").JSX.Element;
 /**
  * Semantic `<aside>` element.
  * Use for supplementary content tangentially related to the main content:
  * sidebars, callout boxes, related-link panels.
  */
 export interface AsideProps extends React.HTMLAttributes<HTMLElement>, SurfaceProps {
+    color?: SemanticColor;
     children: React.ReactNode;
 }
 export declare const Aside: React.ForwardRefExoticComponent<AsideProps & React.RefAttributes<HTMLElement>>;
@@ -77,12 +106,22 @@ export declare const Aside: React.ForwardRefExoticComponent<AsideProps & React.R
  * <Nav aria-label="Product categories">...</Nav>
  * ```
  */
-export interface NavProps extends React.HTMLAttributes<HTMLElement> {
+export interface NavProps extends React.HTMLAttributes<HTMLElement>, SurfaceProps {
     /** REQUIRED — describes the purpose of this navigation region for screen readers. */
     "aria-label": string;
+    /** Vertical spacing between top-level children. */
+    spacing?: "none" | "xs" | "sm" | "md" | "lg" | "xl";
+    /** Flex gap between flex-row children (use with `layout="flex"`). */
+    gap?: "none" | "2xs" | "xs" | "sm" | "md" | "lg";
+    /** Optional layout — `flex` lays out children in a row with the configured `gap`; `flex-wrap` adds `flex-wrap`. */
+    layout?: "default" | "flex" | "flex-wrap";
+    /** Colour cascaded onto nav children. */
+    color?: "default" | "primary" | "muted" | "faint";
+    /** Cascaded text size for nav children. */
+    textSize?: "xs" | "sm" | "base" | "lg";
     children: React.ReactNode;
 }
-export declare function Nav({ className, children, ...props }: NavProps): import("react/jsx-runtime").JSX.Element;
+export declare function Nav({ surface, padding, rounded, border, shadow, spacing, gap, layout, color, textSize, className, children, ...props }: NavProps): import("react/jsx-runtime").JSX.Element;
 /**
  * Semantic `<header>` element for block-level component headers.
  * Use inside `Section`, `Article`, or card bodies — NOT as the page-level header.
@@ -90,9 +129,9 @@ export declare function Nav({ className, children, ...props }: NavProps): import
  * @example
  * ```tsx
  * <Article>
- *   <BlockHeader className="mb-4">
- *     <Heading level={2}>Post title</Heading>
- *   </BlockHeader>
+ * <BlockHeader className="mb-4">
+ * <Heading level={2}>Post title</Heading>
+ * </BlockHeader>
  * </Article>
  * ```
  */
@@ -114,37 +153,85 @@ export declare function BlockFooter({ className, surface, padding, rounded, bord
  * @example
  * ```tsx
  * <Ul className="space-y-2">
- *   <Li>Item one</Li>
- *   <Li>Item two</Li>
+ * <Li>Item one</Li>
+ * <Li>Item two</Li>
  * </Ul>
  * ```
  */
+/** Marker presets for `<Ul>` / `<Ol>`. */
+export type ListMarker = "disc" | "decimal" | "none" | "check" | "arrow";
+/** Spacing between list items. */
+export type ListSpacing = "none" | "2xs" | "tight" | "comfortable" | "loose";
+/** Indent (left padding) applied to the list for marker visibility. */
+export type ListIndent = "none" | "sm" | "md" | "lg" | "xl";
+/** Typography size cascaded onto list items. */
+export type ListSize = "xs" | "sm" | "base" | "lg";
+/** Colour variant cascaded onto list items. */
+export type ListColor = "default" | "primary" | "muted" | "faint";
+type UlPaddingX = "none" | "x-xs" | "x-sm" | "x-md" | "x-lg";
+type UlPaddingY = "none" | "y-2xs" | "y-xs" | "y-sm" | "y-md" | "y-lg" | "y-bottom-xs";
 export interface UlProps extends React.HTMLAttributes<HTMLUListElement> {
+    /** Marker style — replaces consumer `list-disc`/`list-none` className. */
+    marker?: ListMarker;
+    /** Vertical spacing between items — replaces consumer `space-y-N`. */
+    spacing?: ListSpacing;
+    /** Left padding — replaces consumer `pl-N`. */
+    indent?: ListIndent;
+    /** Horizontal padding — replaces consumer `px-N` className on list shells. */
+    paddingX?: UlPaddingX;
+    /** Vertical padding — replaces consumer `py-N`/`pb-N` className on list shells. */
+    paddingY?: UlPaddingY;
+    /** Typography size cascaded onto list items. */
+    size?: ListSize;
+    /** Colour variant cascaded onto list items. */
+    color?: ListColor;
     children: React.ReactNode;
 }
-export declare function Ul({ className, children, ...props }: UlProps): import("react/jsx-runtime").JSX.Element;
+export declare const Ul: React.ForwardRefExoticComponent<UlProps & React.RefAttributes<HTMLUListElement>>;
 /**
  * Semantic `<ol>` (ordered list) element.
  *
  * @example
  * ```tsx
  * <Ol className="list-decimal pl-4 space-y-1">
- *   <Li>Step one</Li>
- *   <Li>Step two</Li>
+ * <Li>Step one</Li>
+ * <Li>Step two</Li>
  * </Ol>
  * ```
  */
 export interface OlProps extends React.HTMLAttributes<HTMLOListElement> {
+    /** Marker style — defaults to `"decimal"` for ordered lists. */
+    marker?: ListMarker;
+    /** Vertical spacing between items — replaces consumer `space-y-N`. */
+    spacing?: ListSpacing;
+    /** Left padding — replaces consumer `pl-N`. */
+    indent?: ListIndent;
+    /** Typography size cascaded onto list items. */
+    size?: ListSize;
+    /** Colour variant cascaded onto list items. */
+    color?: ListColor;
     children: React.ReactNode;
 }
-export declare function Ol({ className, children, ...props }: OlProps): import("react/jsx-runtime").JSX.Element;
+export declare function Ol({ marker, spacing, indent, size, color, className, children, ...props }: OlProps): import("react/jsx-runtime").JSX.Element;
 /**
  * Semantic `<li>` (list item) element. Use inside `Ul` or `Ol`.
  */
+type LiLayout = "default" | "flex" | "flex-start" | "flex-center";
+type LiGap = "none" | "1" | "2" | "3" | "4";
+type LiTextSize = "xs" | "sm" | "base" | "lg";
+type LiColor = "default" | "muted" | "faint";
 export interface LiProps extends React.LiHTMLAttributes<HTMLLIElement> {
+    /** Layout / alignment preset. Replaces raw `flex items-center` / `flex items-start` className. */
+    layout?: LiLayout;
+    /** Gap between children (for `layout="flex*"`). */
+    gap?: LiGap;
+    /** Cascaded typography size. */
+    textSize?: LiTextSize;
+    /** Cascaded text colour. */
+    color?: LiColor;
     children: React.ReactNode;
 }
-export declare function Li({ className, children, ...props }: LiProps): import("react/jsx-runtime").JSX.Element;
+export declare function Li({ layout, gap, textSize, color, className, children, ...props }: LiProps): import("react/jsx-runtime").JSX.Element;
 type TableVariant = "default" | "striped" | "bordered";
 type TableSize = "sm" | "md" | "lg";
 export interface TableProps extends Omit<React.TableHTMLAttributes<HTMLTableElement>, "border">, SurfaceProps {
@@ -154,35 +241,77 @@ export interface TableProps extends Omit<React.TableHTMLAttributes<HTMLTableElem
     children: React.ReactNode;
 }
 export declare function Table({ variant, size, stickyHeader, className, surface, padding, rounded, border, shadow, children, ...props }: TableProps): import("react/jsx-runtime").JSX.Element;
+type TheadSurface = "none" | "default" | "muted" | "subtle";
 export interface TheadProps extends React.HTMLAttributes<HTMLTableSectionElement> {
+    /** Background tone for the header row. */
+    surface?: TheadSurface;
     children: React.ReactNode;
 }
-export declare function Thead({ className, children, ...props }: TheadProps): import("react/jsx-runtime").JSX.Element;
+export declare function Thead({ surface, className, children, ...props }: TheadProps): import("react/jsx-runtime").JSX.Element;
 export interface TbodyProps extends React.HTMLAttributes<HTMLTableSectionElement> {
     children: React.ReactNode;
 }
 export declare function Tbody({ className, children, ...props }: TbodyProps): import("react/jsx-runtime").JSX.Element;
+type TrBorder = "none" | "default" | "subtle" | "strong";
+type TrSurface = "none" | "default" | "muted" | "subtle";
 export interface TrProps extends React.HTMLAttributes<HTMLTableRowElement> {
     hover?: boolean;
+    border?: TrBorder;
+    surface?: TrSurface;
     children: React.ReactNode;
 }
-export declare function Tr({ hover, className, children, ...props }: TrProps): import("react/jsx-runtime").JSX.Element;
+export declare function Tr({ hover, border, surface, className, children, ...props }: TrProps): import("react/jsx-runtime").JSX.Element;
 type CellAlign = "left" | "center" | "right";
+type CellTypographySize = "xs" | "sm" | "base" | "lg" | "xl" | "2xl";
+type CellTypographyWeight = "normal" | "medium" | "semibold" | "bold";
+type CellPadding = "none" | "xs" | "xs-tall" | "xs-3" | "sm" | "sm-tall" | "md" | "lg" | "lg-tight" | "lg-3" | "compact";
+type CellColor = "default" | "primary" | "muted" | "faint" | "success" | "warning" | "error" | "info";
+type CellPaddingX = "none" | "xs" | "sm" | "md" | "lg";
+type CellPaddingY = "none" | "2xs" | "xs" | "sm" | "md";
+type CellPaddingSide = "none" | "pr-md" | "pl-md" | "pr-lg" | "pl-lg" | "pt-md" | "pb-md";
 export interface ThProps extends React.ThHTMLAttributes<HTMLTableCellElement> {
     align?: CellAlign;
+    size?: CellTypographySize;
+    weight?: CellTypographyWeight;
+    padding?: CellPadding;
+    /** X-only padding override. Use when `padding` doesn't fit (e.g. dense table needs `px-3` only). */
+    paddingX?: CellPaddingX;
+    /** Y-only padding override. */
+    paddingY?: CellPaddingY;
+    /** One-sided padding (right/left/top/bottom only) — for asymmetric table cells. */
+    paddingSide?: CellPaddingSide;
+    color?: CellColor;
     children?: React.ReactNode;
 }
-export declare function Th({ align, className, children, ...props }: ThProps): import("react/jsx-runtime").JSX.Element;
+export declare function Th({ align, size, weight, padding, paddingX, paddingY, paddingSide, color, className, children, ...props }: ThProps): import("react/jsx-runtime").JSX.Element;
 export interface TdProps extends React.TdHTMLAttributes<HTMLTableCellElement> {
     align?: CellAlign;
+    size?: CellTypographySize;
+    weight?: CellTypographyWeight;
+    padding?: CellPadding;
+    /** X-only padding override. */
+    paddingX?: CellPaddingX;
+    /** Y-only padding override. */
+    paddingY?: CellPaddingY;
+    /** One-sided padding (right/left/top/bottom only) — for asymmetric table cells. */
+    paddingSide?: CellPaddingSide;
+    color?: CellColor;
     children?: React.ReactNode;
 }
-export declare function Td({ align, className, children, ...props }: TdProps): import("react/jsx-runtime").JSX.Element;
+export declare function Td({ align, size, weight, padding, paddingX, paddingY, paddingSide, color, className, children, ...props }: TdProps): import("react/jsx-runtime").JSX.Element;
+type CodeSize = "xs" | "sm" | "base";
+type CodePadding = "none" | "xs" | "sm" | "inline";
+type CodeRounded = "none" | "default" | "sm" | "md" | "lg";
+type CodeSurface = "none" | "muted" | "subtle" | "default";
 export interface CodeProps extends React.HTMLAttributes<HTMLElement> {
     color?: "default" | "primary" | "error" | "success";
+    size?: CodeSize;
+    padding?: CodePadding;
+    rounded?: CodeRounded;
+    surface?: CodeSurface;
     children: React.ReactNode;
 }
-export declare function Code({ color, className, children, ...props }: CodeProps): import("react/jsx-runtime").JSX.Element;
+export declare function Code({ color, size, padding, rounded, surface, className, children, ...props }: CodeProps): import("react/jsx-runtime").JSX.Element;
 export interface PreProps extends React.HTMLAttributes<HTMLPreElement>, SurfaceProps {
     children: React.ReactNode;
 }
@@ -203,15 +332,27 @@ export declare function Figcaption({ className, children, ...props }: Figcaption
 type DlVariant = "stacked" | "inline";
 export interface DlProps extends React.HTMLAttributes<HTMLDListElement>, SurfaceProps {
     variant?: DlVariant;
+    /**
+     * Render a themed top-border between adjacent dt/dd term pairs — replaces
+     * the consumer `divide-y divide-zinc-100 dark:divide-zinc-800` className
+     * pattern. Tokens flow through `var(--appkit-color-border)`.
+     */
+    divide?: boolean | "default" | "subtle";
     children: React.ReactNode;
 }
-export declare function Dl({ variant, className, surface, padding, rounded, border, shadow, children, ...props }: DlProps): import("react/jsx-runtime").JSX.Element;
+export declare function Dl({ variant, divide, className, surface, padding, rounded, border, shadow, children, ...props }: DlProps): import("react/jsx-runtime").JSX.Element;
+type DtDdColor = "default" | "primary" | "muted" | "faint";
+type DtDdWeight = "normal" | "medium" | "semibold" | "bold";
 export interface DtProps extends React.HTMLAttributes<HTMLElement> {
+    color?: DtDdColor;
+    weight?: DtDdWeight;
     children: React.ReactNode;
 }
-export declare function Dt({ className, children, ...props }: DtProps): import("react/jsx-runtime").JSX.Element;
+export declare function Dt({ color, weight, className, children, ...props }: DtProps): import("react/jsx-runtime").JSX.Element;
 export interface DdProps extends React.HTMLAttributes<HTMLElement> {
+    color?: DtDdColor;
+    weight?: DtDdWeight;
     children: React.ReactNode;
 }
-export declare function Dd({ className, children, ...props }: DdProps): import("react/jsx-runtime").JSX.Element;
+export declare function Dd({ color, weight, className, children, ...props }: DdProps): import("react/jsx-runtime").JSX.Element;
 export {};