@skdx/react-blocks 0.1.0 → 0.35.0

package/dist/sign-up-page/SignUpPage.d.ts

@@ -0,0 +1,21 @@
+import type * as React from 'react';
+import type { SignUpPageProps } from './types.js';
+/**
+ * Sign-up block: an error alert, one button per third-party provider, and the
+ * credentials form — name, email, password, confirmation and terms — reporting
+ * through `onSignUp`.
+ *
+ * @example
+ * ```tsx
+ * <SignUpPage
+ *   confirmPasswordLabel="Confirm password"
+ *   terms={<>I accept the <a href="/terms">terms</a>.</>}
+ *   error={error}
+ *   onSignUp={(detail) => void register(detail)}
+ * />
+ * ```
+ */
+export declare const SignUpPage: {
+    ({ title, providers, error, pending, nameLabel, emailLabel, passwordLabel, confirmPasswordLabel, passwordMismatchMessage, terms, submitLabel, getProviderLabel, footer, onSignUp, children, ...props }: SignUpPageProps): React.ReactNode;
+    displayName: string;
+};

package/dist/sign-up-page/SignUpPage.js

@@ -0,0 +1,2 @@
+'use client';
+import{Button as I,Checkbox as z,Divider as G,Field as u,Form as J,PasswordInput as R,TextField as w}from"@skdx/react";import{PasswordInputField as T,PasswordInputToggle as q}from"@skdx/react/primitives/password-input";import{TextFieldInput as E}from"@skdx/react/primitives/text-field";import*as C from"react";import{Alert as L,Heading as _}from"@skdx/react";import{jsx as g,jsxs as O}from"react/jsx-runtime";var h=({parts:e,title:r,error:i,footer:a,children:s,...l})=>{let p=C.useId();return g("section",{"aria-labelledby":p,...l,...e.root,children:O("div",{...e.panel,children:[g(_,{as:"h1",id:p,...e.title,children:r}),i?g(L,{status:"danger",...e.error,children:i}):null,s,a&&e.footer?g("div",{...e.footer,children:a}):null]})})};h.displayName="AuthPanel";function f(e,r){let i=e.get(r);return typeof i=="string"?i:""}function W(...e){let r="";for(let i of e)i&&(r=r?`${r} ${i}`:i);return r}function n(e,r,i){let a=r==="root",s=a?`skdx-${e}`:`skdx-${e}__${r}`,l={className:W(s,i),"data-part":r};return a&&(l["data-skdx-component"]=e),l}import{defaultProviderLabel as K}from"../sign-in-page/SignInPage.js";import{jsx as t,jsxs as c}from"react/jsx-runtime";var v="confirmPassword";function Q(e){let r=e.elements.namedItem(v);return r instanceof HTMLInputElement?r:null}var N=({title:e="Create account",providers:r,error:i,pending:a=!1,nameLabel:s,emailLabel:l="Email",passwordLabel:p="Password",confirmPasswordLabel:P,passwordMismatchMessage:H="Passwords do not match",terms:x,submitLabel:M="Create account",getProviderLabel:U=K,footer:D,onSignUp:F,children:V,...k})=>{let b=r??[],$=o=>{o.preventDefault();let d=o.currentTarget,m=new FormData(d),y=f(m,"password"),A=P===void 0?null:Q(d);if(A&&A.value!==y){A.setCustomValidity(H),d.reportValidity();return}let S={providerId:"credentials",email:f(m,"email"),password:y};s!==void 0&&(S.name=f(m,"name")),x!==void 0&&(S.termsAccepted=m.get("terms")!==null),F?.(S)},B=o=>{let d=o.target;d instanceof HTMLInputElement&&d.name===v&&d.setCustomValidity("")};return c(h,{...k,parts:{root:n("sign-up-page","root",k.className),panel:n("sign-up-page","panel"),title:n("sign-up-page","title"),error:n("sign-up-page","error"),footer:n("sign-up-page","footer")},title:e,error:i,footer:D,children:[b.length>0?t("div",{...n("sign-up-page","providers"),children:b.map(o=>t(I,{type:"button","data-provider":o.id,onClick:()=>{F?.({providerId:o.id})},...n("sign-up-page","provider"),children:U(o)},o.id))}):null,b.length>0?t(G,{...n("sign-up-page","divider")}):null,c(J,{onSubmit:$,onChange:B,...n("sign-up-page","form"),children:[s!==void 0?t(u,{label:s,required:!0,...n("sign-up-page","field"),children:t(w,{name:"name",required:!0,children:t(E,{autoComplete:"name"})})}):null,t(u,{label:l,required:!0,...n("sign-up-page","field"),children:t(w,{name:"email",required:!0,children:t(E,{type:"email",autoComplete:"email"})})}),t(u,{label:p,required:!0,...n("sign-up-page","field"),children:c(R,{name:"password",required:!0,children:[t(T,{autoComplete:"new-password"}),t(q,{})]})}),P!==void 0?t(u,{label:P,required:!0,...n("sign-up-page","field"),children:c(R,{name:v,required:!0,children:[t(T,{autoComplete:"new-password"}),t(q,{})]})}):null,V,x!==void 0?t(u,{label:x,required:!0,...n("sign-up-page","terms"),children:t(z,{name:"terms",required:!0})}):null,t(I,{type:"submit",loading:a,disabled:a,...n("sign-up-page","submit"),children:M})]})]})};N.displayName="SignUpPage";export{N as SignUpPage};

package/dist/sign-up-page/index.d.cts

@@ -0,0 +1,2 @@
+export { SignUpPage } from './SignUpPage.cjs';
+export type { SignUpPageProps, SignUpDetail } from './types.cjs';

package/dist/sign-up-page/index.d.ts

@@ -0,0 +1,2 @@
+export { SignUpPage } from './SignUpPage.js';
+export type { SignUpPageProps, SignUpDetail } from './types.js';

package/dist/sign-up-page/types.d.cts

@@ -0,0 +1,100 @@
+import type * as React from 'react';
+import type { SignInProvider } from '../sign-in-page/index.cjs';
+/** What {@link SignUpPageProps.onSignUp} is called with when a provider or the form is used. */
+export interface SignUpDetail {
+    /** The `id` of the provider the user chose, or `'credentials'` for the form. */
+    providerId: string;
+    /**
+     * Name submitted by the credentials form, present only while the name field renders.
+     * @default undefined — no name field rendered, or a provider button was used.
+     */
+    name?: string | undefined;
+    /**
+     * Email address submitted by the credentials form.
+     * @default undefined — a provider button carries no field values.
+     */
+    email?: string | undefined;
+    /**
+     * Password submitted by the credentials form, already matched against the confirmation.
+     * @default undefined — a provider button carries no field values.
+     */
+    password?: string | undefined;
+    /**
+     * Whether the terms checkbox was ticked, present only while the terms field renders.
+     * @default undefined — no terms field rendered, or a provider button was used.
+     */
+    termsAccepted?: boolean | undefined;
+}
+/** Props for the {@link SignUpPage} block. */
+export interface SignUpPageProps extends React.ComponentPropsWithRef<'section'> {
+    /**
+     * Heading text, rendered into a derived `<h1>` that names the section.
+     * @default 'Create account'
+     */
+    title?: string | undefined;
+    /**
+     * Third-party providers, each rendering one button above the credentials form.
+     * @default undefined — no provider region and no divider render.
+     */
+    providers?: ReadonlyArray<SignInProvider> | undefined;
+    /**
+     * Message rendered into a derived error Alert above the form; the block never clears it.
+     * @default undefined — no error region renders.
+     */
+    error?: string | undefined;
+    /**
+     * Marks the request in flight, making the submit button busy and unusable while the fields stay editable.
+     * @default false
+     */
+    pending?: boolean | undefined;
+    /**
+     * Label of the name field; supplying it is what makes that field render at all.
+     * @default undefined — no name field renders.
+     */
+    nameLabel?: string | undefined;
+    /**
+     * Label of the email field in the credentials form.
+     * @default 'Email'
+     */
+    emailLabel?: string | undefined;
+    /**
+     * Label of the password field in the credentials form.
+     * @default 'Password'
+     */
+    passwordLabel?: string | undefined;
+    /**
+     * Label of the confirmation field; supplying it is what makes that field render at all.
+     * @default undefined — no confirmation field renders and no matching is done.
+     */
+    confirmPasswordLabel?: string | undefined;
+    /**
+     * Validation message shown on the confirmation field when the two passwords differ.
+     * @default 'Passwords do not match'
+     */
+    passwordMismatchMessage?: string | undefined;
+    /**
+     * Terms copy and links, rendered as the label of a required checkbox before the submit button.
+     * @default undefined — no terms field renders.
+     */
+    terms?: React.ReactNode | undefined;
+    /**
+     * Text of the credentials form's submit button.
+     * @default 'Create account'
+     */
+    submitLabel?: string | undefined;
+    /**
+     * Words a provider button's text from its entry, replacing the built-in wording.
+     * @default defaultProviderLabel — reads "Sign in with Google".
+     */
+    getProviderLabel?: ((provider: SignInProvider) => string) | undefined;
+    /**
+     * Navigation rendered below the form, such as a link back to the sign-in page.
+     * @default undefined — no footer region renders.
+     */
+    footer?: React.ReactNode | undefined;
+    /**
+     * Fires when a provider button is activated or the form is submitted with matching, valid fields.
+     * @default undefined — no-op if omitted.
+     */
+    onSignUp?: ((detail: SignUpDetail) => void) | undefined;
+}

package/dist/sign-up-page/types.d.ts

@@ -0,0 +1,100 @@
+import type * as React from 'react';
+import type { SignInProvider } from '../sign-in-page/index.js';
+/** What {@link SignUpPageProps.onSignUp} is called with when a provider or the form is used. */
+export interface SignUpDetail {
+    /** The `id` of the provider the user chose, or `'credentials'` for the form. */
+    providerId: string;
+    /**
+     * Name submitted by the credentials form, present only while the name field renders.
+     * @default undefined — no name field rendered, or a provider button was used.
+     */
+    name?: string | undefined;
+    /**
+     * Email address submitted by the credentials form.
+     * @default undefined — a provider button carries no field values.
+     */
+    email?: string | undefined;
+    /**
+     * Password submitted by the credentials form, already matched against the confirmation.
+     * @default undefined — a provider button carries no field values.
+     */
+    password?: string | undefined;
+    /**
+     * Whether the terms checkbox was ticked, present only while the terms field renders.
+     * @default undefined — no terms field rendered, or a provider button was used.
+     */
+    termsAccepted?: boolean | undefined;
+}
+/** Props for the {@link SignUpPage} block. */
+export interface SignUpPageProps extends React.ComponentPropsWithRef<'section'> {
+    /**
+     * Heading text, rendered into a derived `<h1>` that names the section.
+     * @default 'Create account'
+     */
+    title?: string | undefined;
+    /**
+     * Third-party providers, each rendering one button above the credentials form.
+     * @default undefined — no provider region and no divider render.
+     */
+    providers?: ReadonlyArray<SignInProvider> | undefined;
+    /**
+     * Message rendered into a derived error Alert above the form; the block never clears it.
+     * @default undefined — no error region renders.
+     */
+    error?: string | undefined;
+    /**
+     * Marks the request in flight, making the submit button busy and unusable while the fields stay editable.
+     * @default false
+     */
+    pending?: boolean | undefined;
+    /**
+     * Label of the name field; supplying it is what makes that field render at all.
+     * @default undefined — no name field renders.
+     */
+    nameLabel?: string | undefined;
+    /**
+     * Label of the email field in the credentials form.
+     * @default 'Email'
+     */
+    emailLabel?: string | undefined;
+    /**
+     * Label of the password field in the credentials form.
+     * @default 'Password'
+     */
+    passwordLabel?: string | undefined;
+    /**
+     * Label of the confirmation field; supplying it is what makes that field render at all.
+     * @default undefined — no confirmation field renders and no matching is done.
+     */
+    confirmPasswordLabel?: string | undefined;
+    /**
+     * Validation message shown on the confirmation field when the two passwords differ.
+     * @default 'Passwords do not match'
+     */
+    passwordMismatchMessage?: string | undefined;
+    /**
+     * Terms copy and links, rendered as the label of a required checkbox before the submit button.
+     * @default undefined — no terms field renders.
+     */
+    terms?: React.ReactNode | undefined;
+    /**
+     * Text of the credentials form's submit button.
+     * @default 'Create account'
+     */
+    submitLabel?: string | undefined;
+    /**
+     * Words a provider button's text from its entry, replacing the built-in wording.
+     * @default defaultProviderLabel — reads "Sign in with Google".
+     */
+    getProviderLabel?: ((provider: SignInProvider) => string) | undefined;
+    /**
+     * Navigation rendered below the form, such as a link back to the sign-in page.
+     * @default undefined — no footer region renders.
+     */
+    footer?: React.ReactNode | undefined;
+    /**
+     * Fires when a provider button is activated or the form is submitted with matching, valid fields.
+     * @default undefined — no-op if omitted.
+     */
+    onSignUp?: ((detail: SignUpDetail) => void) | undefined;
+}

package/dist/stat-card/StatCard.cjs

@@ -0,0 +1,2 @@
+'use client';
+"use strict";var N=Object.create;var u=Object.defineProperty;var R=Object.getOwnPropertyDescriptor;var $=Object.getOwnPropertyNames;var A=Object.getPrototypeOf,T=Object.prototype.hasOwnProperty;var h=(t,a)=>{for(var d in a)u(t,d,{get:a[d],enumerable:!0})},P=(t,a,d,i)=>{if(a&&typeof a=="object"||typeof a=="function")for(let s of $(a))!T.call(t,s)&&s!==d&&u(t,s,{get:()=>a[s],enumerable:!(i=R(a,s))||i.enumerable});return t};var H=(t,a,d)=>(d=t!=null?N(A(t)):{},P(a||!t||!t.__esModule?u(d,"default",{value:t,enumerable:!0}):d,t)),V=t=>P(u({},"__esModule",{value:!0}),t);var w={};h(w,{StatCard:()=>c});module.exports=V(w);var g=H(require("react"),1),n=require("@skdx/react");function _(...t){let a="";for(let d of t)d&&(a=a?`${a} ${d}`:d);return a}function e(t,a,d){let i=a==="root",s=i?`skdx-${t}`:`skdx-${t}__${a}`,l={className:_(s,d),"data-part":a};return i&&(l["data-skdx-component"]=t),l}var r=require("react/jsx-runtime"),c=({label:t,value:a,change:d,trend:i,sentiment:s,changeLabel:l,trendIcon:f,icon:x,description:m,progress:v,visual:b,footer:y,actions:k,loading:o=!1,...S})=>{let p=g.useId(),C=d!==void 0&&!o;return(0,r.jsxs)("div",{role:"group","aria-labelledby":p,"aria-busy":o||void 0,"data-trend":i,"data-sentiment":s,"data-state":o?"loading":void 0,...S,...e("stat-card","root",S.className),children:[(0,r.jsxs)("div",{...e("stat-card","header"),children:[x?(0,r.jsx)("span",{"aria-hidden":"true",...e("stat-card","icon"),children:x}):null,(0,r.jsx)("span",{id:p,...e("stat-card","label"),children:t}),k?(0,r.jsx)("div",{...e("stat-card","actions"),children:k}):null]}),(0,r.jsxs)("div",{...e("stat-card","body"),children:[(0,r.jsx)("span",{...e("stat-card","value"),children:o?(0,r.jsx)(n.Skeleton,{shape:"line"}):(0,r.jsx)(n.Text,{as:"span",variant:"numeric",children:a})}),C?(0,r.jsxs)("span",{"data-trend":i,"data-sentiment":s,...e("stat-card","trend"),children:[f?(0,r.jsx)("span",{"aria-hidden":"true",...e("stat-card","trend-icon"),children:f}):null,l?(0,r.jsx)(n.VisuallyHidden,{children:l}):null,d]}):null]}),m?(0,r.jsx)(n.Text,{as:"p",tone:"muted",...e("stat-card","description"),children:m}):null,typeof v=="number"?(0,r.jsx)(n.Progress,{value:v,"aria-labelledby":p,...e("stat-card","progress")}):null,b?(0,r.jsx)("div",{...e("stat-card","visual"),children:b}):null,y?(0,r.jsx)("div",{...e("stat-card","footer"),children:y}):null]})};c.displayName="StatCard";0&&(module.exports={StatCard});

package/dist/stat-card/StatCard.d.cts

@@ -0,0 +1,22 @@
+import * as React from 'react';
+import type { StatCardProps } from './types.cjs';
+/**
+ * KPI tile block: a label, a value, an optional trend with sentiment colour,
+ * a description, a derived progress bar and a visual region, all inside one
+ * `role="group"` named by its own label.
+ *
+ * @example
+ * ```tsx
+ * <StatCard
+ *   label="Revenue"
+ *   value="$12,400"
+ *   change="+12.4%"
+ *   trend="up"
+ *   sentiment="positive"
+ * />
+ * ```
+ */
+export declare const StatCard: {
+    ({ label, value, change, trend, sentiment, changeLabel, trendIcon, icon, description, progress, visual, footer, actions, loading, ...props }: StatCardProps): React.ReactNode;
+    displayName: string;
+};

package/dist/stat-card/StatCard.d.ts

@@ -0,0 +1,22 @@
+import * as React from 'react';
+import type { StatCardProps } from './types.js';
+/**
+ * KPI tile block: a label, a value, an optional trend with sentiment colour,
+ * a description, a derived progress bar and a visual region, all inside one
+ * `role="group"` named by its own label.
+ *
+ * @example
+ * ```tsx
+ * <StatCard
+ *   label="Revenue"
+ *   value="$12,400"
+ *   change="+12.4%"
+ *   trend="up"
+ *   sentiment="positive"
+ * />
+ * ```
+ */
+export declare const StatCard: {
+    ({ label, value, change, trend, sentiment, changeLabel, trendIcon, icon, description, progress, visual, footer, actions, loading, ...props }: StatCardProps): React.ReactNode;
+    displayName: string;
+};

package/dist/stat-card/StatCard.js

@@ -0,0 +1,2 @@
+'use client';
+import*as S from"react";import{Progress as N,Skeleton as R,Text as k,VisuallyHidden as $}from"@skdx/react";function C(...e){let r="";for(let d of e)d&&(r=r?`${r} ${d}`:d);return r}function t(e,r,d){let s=r==="root",i=s?`skdx-${e}`:`skdx-${e}__${r}`,n={className:C(i,d),"data-part":r};return s&&(n["data-skdx-component"]=e),n}import{jsx as a,jsxs as o}from"react/jsx-runtime";var P=({label:e,value:r,change:d,trend:s,sentiment:i,changeLabel:n,trendIcon:p,icon:c,description:f,progress:x,visual:m,footer:v,actions:b,loading:l=!1,...y})=>{let u=S.useId(),g=d!==void 0&&!l;return o("div",{role:"group","aria-labelledby":u,"aria-busy":l||void 0,"data-trend":s,"data-sentiment":i,"data-state":l?"loading":void 0,...y,...t("stat-card","root",y.className),children:[o("div",{...t("stat-card","header"),children:[c?a("span",{"aria-hidden":"true",...t("stat-card","icon"),children:c}):null,a("span",{id:u,...t("stat-card","label"),children:e}),b?a("div",{...t("stat-card","actions"),children:b}):null]}),o("div",{...t("stat-card","body"),children:[a("span",{...t("stat-card","value"),children:l?a(R,{shape:"line"}):a(k,{as:"span",variant:"numeric",children:r})}),g?o("span",{"data-trend":s,"data-sentiment":i,...t("stat-card","trend"),children:[p?a("span",{"aria-hidden":"true",...t("stat-card","trend-icon"),children:p}):null,n?a($,{children:n}):null,d]}):null]}),f?a(k,{as:"p",tone:"muted",...t("stat-card","description"),children:f}):null,typeof x=="number"?a(N,{value:x,"aria-labelledby":u,...t("stat-card","progress")}):null,m?a("div",{...t("stat-card","visual"),children:m}):null,v?a("div",{...t("stat-card","footer"),children:v}):null]})};P.displayName="StatCard";export{P as StatCard};

package/dist/stat-card/index.d.cts

@@ -0,0 +1,2 @@
+export { StatCard } from './StatCard.cjs';
+export type { StatCardProps } from './types.cjs';

package/dist/stat-card/index.d.ts

@@ -0,0 +1,2 @@
+export { StatCard } from './StatCard.js';
+export type { StatCardProps } from './types.js';

package/dist/stat-card/types.d.cts

@@ -0,0 +1,71 @@
+import type * as React from 'react';
+/** Props for the {@link StatCard} block. */
+export interface StatCardProps extends React.ComponentPropsWithRef<'div'> {
+    /** Name of the metric, rendered into the label that names the group through aria-labelledby. */
+    label: string;
+    /**
+     * The metric's current reading, already formatted by the consumer for its locale.
+     * @default undefined — the value region renders empty.
+     */
+    value?: React.ReactNode | undefined;
+    /**
+     * Already-formatted delta text such as "+12.4%", rendered inside the trend region.
+     * @default undefined — no trend region renders.
+     */
+    change?: string | undefined;
+    /**
+     * Direction of the change only, mirrored to data-trend on the root and the trend part.
+     * @default undefined — no direction is written.
+     */
+    trend?: 'up' | 'down' | 'neutral' | undefined;
+    /**
+     * Whether the change is good or bad, independent of trend, mirrored to data-sentiment.
+     * @default undefined — the trend renders in the skin's neutral colour.
+     */
+    sentiment?: 'positive' | 'negative' | 'neutral' | undefined;
+    /**
+     * Visually hidden text read before the change, such as "Increased by".
+     * @default undefined — only the change text itself is announced.
+     */
+    changeLabel?: string | undefined;
+    /**
+     * Decorative glyph rendered beside the change text inside the trend region.
+     * @default undefined — no trend icon renders.
+     */
+    trendIcon?: React.ReactNode | undefined;
+    /**
+     * Decorative glyph rendered beside the label in the card header.
+     * @default undefined — no icon region renders.
+     */
+    icon?: React.ReactNode | undefined;
+    /**
+     * Supporting text rendered below the value, in the skin's muted tone.
+     * @default undefined — no description region renders.
+     */
+    description?: string | undefined;
+    /**
+     * Percentage from 0 to 100, rendered into a derived Progress named by the label.
+     * @default undefined — no progress bar renders.
+     */
+    progress?: number | undefined;
+    /**
+     * A chart or sparkline the card sizes a region for; the consumer draws its contents.
+     * @default undefined — no visual region renders.
+     */
+    visual?: React.ReactNode | undefined;
+    /**
+     * Content rendered in a footer region below the card's other regions.
+     * @default undefined — no footer region renders.
+     */
+    footer?: React.ReactNode | undefined;
+    /**
+     * Controls rendered at the end of the header, such as a menu button.
+     * @default undefined — no actions region renders.
+     */
+    actions?: React.ReactNode | undefined;
+    /**
+     * Shows a skeleton in the value region and withholds the trend while true.
+     * @default false
+     */
+    loading?: boolean | undefined;
+}

package/dist/stat-card/types.d.ts

@@ -0,0 +1,71 @@
+import type * as React from 'react';
+/** Props for the {@link StatCard} block. */
+export interface StatCardProps extends React.ComponentPropsWithRef<'div'> {
+    /** Name of the metric, rendered into the label that names the group through aria-labelledby. */
+    label: string;
+    /**
+     * The metric's current reading, already formatted by the consumer for its locale.
+     * @default undefined — the value region renders empty.
+     */
+    value?: React.ReactNode | undefined;
+    /**
+     * Already-formatted delta text such as "+12.4%", rendered inside the trend region.
+     * @default undefined — no trend region renders.
+     */
+    change?: string | undefined;
+    /**
+     * Direction of the change only, mirrored to data-trend on the root and the trend part.
+     * @default undefined — no direction is written.
+     */
+    trend?: 'up' | 'down' | 'neutral' | undefined;
+    /**
+     * Whether the change is good or bad, independent of trend, mirrored to data-sentiment.
+     * @default undefined — the trend renders in the skin's neutral colour.
+     */
+    sentiment?: 'positive' | 'negative' | 'neutral' | undefined;
+    /**
+     * Visually hidden text read before the change, such as "Increased by".
+     * @default undefined — only the change text itself is announced.
+     */
+    changeLabel?: string | undefined;
+    /**
+     * Decorative glyph rendered beside the change text inside the trend region.
+     * @default undefined — no trend icon renders.
+     */
+    trendIcon?: React.ReactNode | undefined;
+    /**
+     * Decorative glyph rendered beside the label in the card header.
+     * @default undefined — no icon region renders.
+     */
+    icon?: React.ReactNode | undefined;
+    /**
+     * Supporting text rendered below the value, in the skin's muted tone.
+     * @default undefined — no description region renders.
+     */
+    description?: string | undefined;
+    /**
+     * Percentage from 0 to 100, rendered into a derived Progress named by the label.
+     * @default undefined — no progress bar renders.
+     */
+    progress?: number | undefined;
+    /**
+     * A chart or sparkline the card sizes a region for; the consumer draws its contents.
+     * @default undefined — no visual region renders.
+     */
+    visual?: React.ReactNode | undefined;
+    /**
+     * Content rendered in a footer region below the card's other regions.
+     * @default undefined — no footer region renders.
+     */
+    footer?: React.ReactNode | undefined;
+    /**
+     * Controls rendered at the end of the header, such as a menu button.
+     * @default undefined — no actions region renders.
+     */
+    actions?: React.ReactNode | undefined;
+    /**
+     * Shows a skeleton in the value region and withholds the trend while true.
+     * @default false
+     */
+    loading?: boolean | undefined;
+}

package/dist/usage-card/UsageCard.cjs

@@ -0,0 +1,2 @@
+'use client';
+"use strict";var L=Object.create;var g=Object.defineProperty;var C=Object.getOwnPropertyDescriptor;var A=Object.getOwnPropertyNames;var S=Object.getPrototypeOf,h=Object.prototype.hasOwnProperty;var T=(e,a)=>{for(var t in a)g(e,t,{get:a[t],enumerable:!0})},$=(e,a,t,r)=>{if(a&&typeof a=="object"||typeof a=="function")for(let n of A(a))!h.call(e,n)&&n!==t&&g(e,n,{get:()=>a[n],enumerable:!(r=C(a,n))||r.enumerable});return e};var _=(e,a,t)=>(t=e!=null?L(S(e)):{},$(a||!e||!e.__esModule?g(t,"default",{value:e,enumerable:!0}):t,e)),z=e=>$(g({},"__esModule",{value:!0}),e);var q={};T(q,{UsageCard:()=>f});module.exports=z(q);var y=_(require("react"),1),c=require("@skdx/react");function I(...e){let a="";for(let t of e)t&&(a=a?`${a} ${t}`:t);return a}function i(e,a,t){let r=a==="root",n=r?`skdx-${e}`:`skdx-${e}__${a}`,l={className:I(n,t),"data-part":a};return r&&(l["data-skdx-component"]=e),l}function m(e){return Number.isNaN(e)?0:Math.max(e,0)}function k(e,a){let t=m(e),r=m(a);return r===0?{limit:r,overLimit:t>0,range:null}:{limit:r,overLimit:t>r,range:{max:r,value:Math.min(t,r)}}}var s=require("react/jsx-runtime"),f=({label:e,used:a,limit:t,unit:r,formatValue:n=String,unlimitedLabel:l="Unlimited",description:x,actions:b,footer:v,status:P,...U})=>{let p=y.useId(),R=m(a),o,M=!1,u=null;if(t===null)o=l;else if(t!==void 0){let d=k(R,t);M=d.overLimit,u=d.range,o=`/ ${n(d.limit)}`}return(0,s.jsxs)("div",{role:"group","aria-labelledby":p,"data-state":M?"over-limit":void 0,"data-status":P,...U,...i("usage-card","root",U.className),children:[(0,s.jsxs)("div",{...i("usage-card","header"),children:[(0,s.jsx)("span",{id:p,...i("usage-card","label"),children:e}),b?(0,s.jsx)("div",{...i("usage-card","actions"),children:b}):null]}),(0,s.jsxs)("div",{...i("usage-card","value"),children:[(0,s.jsx)("span",{...i("usage-card","used"),children:n(R)}),o!==void 0?(0,s.jsx)("span",{...i("usage-card","limit"),children:o}):null,r?(0,s.jsx)("span",{...i("usage-card","unit"),children:r}):null]}),u?(0,s.jsx)(c.Progress,{role:"meter",min:0,max:u.max,value:u.value,"aria-labelledby":p,getValueLabel:(d,w,N)=>`${n(d)} / ${n(N)}${r?` ${r}`:""}`,...i("usage-card","progress")}):null,x?(0,s.jsx)(c.Text,{as:"p",tone:"muted",...i("usage-card","description"),children:x}):null,v?(0,s.jsx)("div",{...i("usage-card","footer"),children:v}):null]})};f.displayName="UsageCard";0&&(module.exports={UsageCard});

package/dist/usage-card/UsageCard.d.cts

@@ -0,0 +1,17 @@
+import * as React from 'react';
+import type { UsageCardProps } from './types.cjs';
+/**
+ * Quota tile block: a label, the amount used against a limit, a derived
+ * meter and a status colour, all inside one `role="group"` named by its own
+ * label. Handles a finite, zero, unlimited or unknown limit without division
+ * errors, and derives over-limit from the numbers rather than a status prop.
+ *
+ * @example
+ * ```tsx
+ * <UsageCard label="Storage" used={42} limit={50} unit="GB" />
+ * ```
+ */
+export declare const UsageCard: {
+    ({ label, used, limit, unit, formatValue, unlimitedLabel, description, actions, footer, status, ...props }: UsageCardProps): React.ReactNode;
+    displayName: string;
+};

package/dist/usage-card/UsageCard.d.ts

@@ -0,0 +1,17 @@
+import * as React from 'react';
+import type { UsageCardProps } from './types.js';
+/**
+ * Quota tile block: a label, the amount used against a limit, a derived
+ * meter and a status colour, all inside one `role="group"` named by its own
+ * label. Handles a finite, zero, unlimited or unknown limit without division
+ * errors, and derives over-limit from the numbers rather than a status prop.
+ *
+ * @example
+ * ```tsx
+ * <UsageCard label="Storage" used={42} limit={50} unit="GB" />
+ * ```
+ */
+export declare const UsageCard: {
+    ({ label, used, limit, unit, formatValue, unlimitedLabel, description, actions, footer, status, ...props }: UsageCardProps): React.ReactNode;
+    displayName: string;
+};

package/dist/usage-card/UsageCard.js

@@ -0,0 +1,2 @@
+'use client';
+import*as M from"react";import{Progress as N,Text as L}from"@skdx/react";function P(...t){let r="";for(let a of t)a&&(r=r?`${r} ${a}`:a);return r}function s(t,r,a){let e=r==="root",i=e?`skdx-${t}`:`skdx-${t}__${r}`,l={className:P(i,a),"data-part":r};return e&&(l["data-skdx-component"]=t),l}function g(t){return Number.isNaN(t)?0:Math.max(t,0)}function R(t,r){let a=g(t),e=g(r);return e===0?{limit:e,overLimit:a>0,range:null}:{limit:e,overLimit:a>e,range:{max:e,value:Math.min(a,e)}}}import{jsx as n,jsxs as c}from"react/jsx-runtime";var $=({label:t,used:r,limit:a,unit:e,formatValue:i=String,unlimitedLabel:l="Unlimited",description:p,actions:f,footer:x,status:k,...b})=>{let m=M.useId(),v=g(r),o,U=!1,u=null;if(a===null)o=l;else if(a!==void 0){let d=R(v,a);U=d.overLimit,u=d.range,o=`/ ${i(d.limit)}`}return c("div",{role:"group","aria-labelledby":m,"data-state":U?"over-limit":void 0,"data-status":k,...b,...s("usage-card","root",b.className),children:[c("div",{...s("usage-card","header"),children:[n("span",{id:m,...s("usage-card","label"),children:t}),f?n("div",{...s("usage-card","actions"),children:f}):null]}),c("div",{...s("usage-card","value"),children:[n("span",{...s("usage-card","used"),children:i(v)}),o!==void 0?n("span",{...s("usage-card","limit"),children:o}):null,e?n("span",{...s("usage-card","unit"),children:e}):null]}),u?n(N,{role:"meter",min:0,max:u.max,value:u.value,"aria-labelledby":m,getValueLabel:(d,C,y)=>`${i(d)} / ${i(y)}${e?` ${e}`:""}`,...s("usage-card","progress")}):null,p?n(L,{as:"p",tone:"muted",...s("usage-card","description"),children:p}):null,x?n("div",{...s("usage-card","footer"),children:x}):null]})};$.displayName="UsageCard";export{$ as UsageCard};

package/dist/usage-card/index.d.cts

@@ -0,0 +1,2 @@
+export { UsageCard } from './UsageCard.cjs';
+export type { UsageCardProps } from './types.cjs';

package/dist/usage-card/index.d.ts

@@ -0,0 +1,2 @@
+export { UsageCard } from './UsageCard.js';
+export type { UsageCardProps } from './types.js';

package/dist/usage-card/types.d.cts

@@ -0,0 +1,50 @@
+import type * as React from 'react';
+/** Props for the {@link UsageCard} block. */
+export interface UsageCardProps extends React.ComponentPropsWithRef<'div'> {
+    /** Name of the quota, rendered into the label that names the group through aria-labelledby. */
+    label: string;
+    /** The current amount consumed, formatted by formatValue for the value region and the meter. */
+    used: number;
+    /**
+     * The finite cap `used` is measured against; `null` renders `unlimitedLabel`
+     * instead of a number. No meter or limit text renders when omitted.
+     * @default undefined — the limit is unknown, so no limit text or meter renders.
+     */
+    limit?: number | null | undefined;
+    /**
+     * Unit label rendered after the limit text, such as "GB" or "seats".
+     * @default undefined — no unit region renders.
+     */
+    unit?: string | undefined;
+    /**
+     * Formats `used` and `limit` for the consumer's own locale and precision.
+     * @default String — the raw number is rendered as-is.
+     */
+    formatValue?: ((value: number) => string) | undefined;
+    /**
+     * Text rendered in place of a limit number when `limit` is `null`.
+     * @default 'Unlimited'
+     */
+    unlimitedLabel?: string | undefined;
+    /**
+     * Supporting copy rendered below the meter, in the skin's muted tone.
+     * @default undefined — no description region renders.
+     */
+    description?: string | undefined;
+    /**
+     * Controls rendered at the end of the header, such as a manage-plan link.
+     * @default undefined — no actions region renders.
+     */
+    actions?: React.ReactNode | undefined;
+    /**
+     * Content rendered in a footer region below the card, such as renewal or reset metadata.
+     * @default undefined — no footer region renders.
+     */
+    footer?: React.ReactNode | undefined;
+    /**
+     * Colour role written to data-status, tinting the meter fill and the used amount.
+     * Over-limit is derived automatically; this axis is policy the consumer decides.
+     * @default undefined — the skin's own default colour.
+     */
+    status?: 'info' | 'success' | 'warning' | 'danger' | (string & {}) | undefined;
+}

package/dist/usage-card/types.d.ts

@@ -0,0 +1,50 @@
+import type * as React from 'react';
+/** Props for the {@link UsageCard} block. */
+export interface UsageCardProps extends React.ComponentPropsWithRef<'div'> {
+    /** Name of the quota, rendered into the label that names the group through aria-labelledby. */
+    label: string;
+    /** The current amount consumed, formatted by formatValue for the value region and the meter. */
+    used: number;
+    /**
+     * The finite cap `used` is measured against; `null` renders `unlimitedLabel`
+     * instead of a number. No meter or limit text renders when omitted.
+     * @default undefined — the limit is unknown, so no limit text or meter renders.
+     */
+    limit?: number | null | undefined;
+    /**
+     * Unit label rendered after the limit text, such as "GB" or "seats".
+     * @default undefined — no unit region renders.
+     */
+    unit?: string | undefined;
+    /**
+     * Formats `used` and `limit` for the consumer's own locale and precision.
+     * @default String — the raw number is rendered as-is.
+     */
+    formatValue?: ((value: number) => string) | undefined;
+    /**
+     * Text rendered in place of a limit number when `limit` is `null`.
+     * @default 'Unlimited'
+     */
+    unlimitedLabel?: string | undefined;
+    /**
+     * Supporting copy rendered below the meter, in the skin's muted tone.
+     * @default undefined — no description region renders.
+     */
+    description?: string | undefined;
+    /**
+     * Controls rendered at the end of the header, such as a manage-plan link.
+     * @default undefined — no actions region renders.
+     */
+    actions?: React.ReactNode | undefined;
+    /**
+     * Content rendered in a footer region below the card, such as renewal or reset metadata.
+     * @default undefined — no footer region renders.
+     */
+    footer?: React.ReactNode | undefined;
+    /**
+     * Colour role written to data-status, tinting the meter fill and the used amount.
+     * Over-limit is derived automatically; this axis is policy the consumer decides.
+     * @default undefined — the skin's own default colour.
+     */
+    status?: 'info' | 'success' | 'warning' | 'danger' | (string & {}) | undefined;
+}

package/dist/usage-card/usage.d.cts

@@ -0,0 +1,18 @@
+/** @internal Clamps a raw amount into a safe non-negative number: `NaN` becomes `0`, a negative clamps to `0`. */
+export declare function normalizeUsage(value: number): number;
+/** @internal The `[0, max]` range a finite, positive limit renders as a meter. */
+export interface UsageMeterRange {
+    max: number;
+    value: number;
+}
+/** @internal What a finite limit resolves to: its normalized value, whether usage exceeds it, and the meter range to render. */
+export interface UsageMeterResult {
+    limit: number;
+    overLimit: boolean;
+    range: UsageMeterRange | null;
+}
+/**
+ * @internal Derives the meter range and over-limit flag for a finite limit.
+ * A zero limit renders no meter but counts as over-limit as soon as anything is used.
+ */
+export declare function usageMeter(used: number, limit: number): UsageMeterResult;