@almadar/ui 5.3.1 → 5.5.0

package/dist/components/molecules/ButtonGroup.d.ts

@@ -7,6 +7,11 @@
  */
 import React from 'react';
 export type ButtonGroupVariant = 'default' | 'segmented' | 'toggle';
+/**
+ * Layer 2 visual treatment for the action-cluster (form-actions) pattern —
+ * orthogonal to the semantic `variant` (which conveys grouping shape).
+ */
+export type ActionClusterLook = 'right-aligned-buttons' | 'floating-bar' | 'inline-row' | 'dropdown-menu' | 'command-palette-trigger';
 /** Action button config for form-actions pattern */
 export interface ActionButton {
     label: string;
@@ -63,5 +68,10 @@ export interface ButtonGroupProps {
      * Filter definitions for filter-group pattern
      */
     filters?: readonly FilterDefinition[];
+    /**
+     * Layer 2 visual treatment for the action-cluster (form-actions) pattern.
+     * @default 'right-aligned-buttons'
+     */
+    look?: ActionClusterLook;
 }
 export declare const ButtonGroup: React.FC<ButtonGroupProps>;

package/dist/components/molecules/DataGrid.d.ts

@@ -102,6 +102,11 @@ export interface DataGridProps<T extends EntityRow = EntityRow> extends DataDndP
     renderItem?: (item: T, index: number) => React.ReactNode;
     /** Max items to show before "Show More" button. Defaults to 0 (disabled). */
     pageSize?: number;
+    /**
+     * Layer 2 visual treatment — mirrors the `entity-table` look enum so
+     * data-grid / data-list / entity-table share one knob name from authors.
+     */
+    look?: "dense" | "spacious" | "striped" | "borderless" | "card-rows";
 }
 export declare function DataGrid<T extends EntityRow = EntityRow>({ entity, fields, columns, itemActions, cols, gap, minCardWidth, className, isLoading, error, imageField, selectable, selectionEvent, infiniteScroll, loadMoreEvent, hasMore, children, pageSize, renderItem: schemaRenderItem, dragGroup, accepts, sortable, dropEvent, reorderEvent, positionEvent, dndItemIdField, dndRoot, }: DataGridProps<T>): string | number | bigint | boolean | import("react/jsx-runtime").JSX.Element | Iterable<React.ReactNode> | Promise<string | number | bigint | boolean | React.ReactPortal | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | null | undefined> | null | undefined;
 export declare namespace DataGrid {

package/dist/components/molecules/DataList.d.ts

@@ -116,6 +116,11 @@ export interface DataListProps<T extends EntityRow = EntityRow> extends DataDndP
     renderItem?: (item: T, index: number) => React.ReactNode;
     /** Max items to show before "Show More" button. Defaults to 5. Set to 0 to disable. */
     pageSize?: number;
+    /**
+     * Layer 2 visual treatment — mirrors the `entity-table` look enum so
+     * data-grid / data-list / entity-table share one knob name from authors.
+     */
+    look?: "dense" | "spacious" | "striped" | "borderless" | "card-rows";
 }
 export declare function DataList<T extends EntityRow = EntityRow>({ entity, fields, columns, itemActions, gap, variant, groupBy, senderField, currentUser, className, isLoading, error, reorderable: _reorderable, reorderEvent: _reorderEvent, swipeLeftEvent: _swipeLeftEvent, swipeLeftActions: _swipeLeftActions, swipeRightEvent: _swipeRightEvent, swipeRightActions: _swipeRightActions, longPressEvent: _longPressEvent, infiniteScroll, loadMoreEvent, hasMore, children, pageSize, renderItem: schemaRenderItem, dragGroup, accepts, sortable: sortableProp, dropEvent, reorderEvent: dndReorderEvent, positionEvent, dndItemIdField, dndRoot, }: DataListProps<T>): string | number | bigint | boolean | import("react/jsx-runtime").JSX.Element | Iterable<React.ReactNode> | Promise<string | number | bigint | boolean | React.ReactPortal | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | null | undefined> | null | undefined;
 export declare namespace DataList {

package/dist/components/molecules/EmptyState.d.ts

@@ -1,6 +1,7 @@
 import React from "react";
 import type { EventEmit } from "@almadar/core";
 import type { LucideIcon } from "lucide-react";
+export type EmptyStateLook = "illustrated" | "icon-only" | "text-only" | "mascot";
 export interface EmptyStateProps {
     /**
      * Icon to display. Accepts either:
@@ -22,5 +23,7 @@ export interface EmptyStateProps {
     variant?: "default" | "success" | "error" | "warning" | "info";
     /** Declarative action event — emits UI:{actionEvent} via eventBus when action button is clicked */
     actionEvent?: EventEmit<Record<string, never>>;
+    /** Layer 2 visual treatment — orthogonal to the semantic variant (which carries status color). */
+    look?: EmptyStateLook;
 }
 export declare const EmptyState: React.FC<EmptyStateProps>;

package/dist/components/molecules/FilterGroup.d.ts

@@ -12,6 +12,11 @@
  * Supports Query Singleton pattern via `query` prop for std/Filter behavior.
  */
 import React from "react";
+/**
+ * Layer 2 visual treatment for the filter-group pattern — orthogonal to the
+ * semantic `variant` (which conveys layout / role).
+ */
+export type FilterGroupLook = "toolbar" | "chips" | "pills" | "popover-trigger" | "inline-column-header";
 /** Filter definition from schema */
 export interface FilterDefinition {
     field: string;
@@ -46,6 +51,8 @@ export interface FilterGroupProps {
     query?: string;
     /** Loading state indicator */
     isLoading?: boolean;
+    /** Layer 2 visual treatment — orthogonal to the semantic variant. */
+    look?: FilterGroupLook;
 }
 /**
  * FilterGroup - Renders filter controls for entity data

package/dist/components/molecules/Modal.d.ts

@@ -7,6 +7,11 @@
 import React from "react";
 import type { EventEmit } from "@almadar/core";
 export type ModalSize = "sm" | "md" | "lg" | "xl" | "full";
+/**
+ * Layer 2 visual treatment for the modal pattern — orthogonal to the semantic
+ * `size` (which conveys content scale).
+ */
+export type ModalLook = "centered-card" | "top-sheet" | "side-drawer" | "full-screen";
 export interface ModalProps {
     /** Whether the modal is open (defaults to true when rendered by slot wrapper) */
     isOpen?: boolean;
@@ -25,5 +30,7 @@ export interface ModalProps {
     closeEvent?: EventEmit<Record<string, never>>;
     /** Enable swipe-down-to-close on mobile bottom sheet (default: true) */
     swipeDownToClose?: boolean;
+    /** Layer 2 visual treatment — orthogonal to the semantic variant. */
+    look?: ModalLook;
 }
 export declare const Modal: React.FC<ModalProps>;

package/dist/components/molecules/StatDisplay.d.ts

@@ -6,6 +6,7 @@
  * No entity prop, no data fetching, no hooks beyond icon resolution.
  */
 import React from 'react';
+export type StatDisplayLook = 'elevated' | 'flat' | 'progress-backed' | 'gauge' | 'sparkline';
 export interface StatDisplayProps {
     /** Display label (e.g., "Total", "Remaining") */
     label: string;
@@ -43,6 +44,8 @@ export interface StatDisplayProps {
     variant?: 'default' | 'primary' | 'success' | 'warning' | 'error' | 'info';
     /** Compact mode (inline, no card wrapper) */
     compact?: boolean;
+    /** Layer 2 visual treatment. */
+    look?: StatDisplayLook;
     /** Additional CSS classes */
     className?: string;
     /** Loading state */

package/dist/components/organisms/Chart.d.ts

@@ -16,6 +16,23 @@
  */
 import React from "react";
 export type ChartType = "bar" | "line" | "pie" | "area" | "donut" | "scatter" | "histogram";
+/**
+ * Layer 2 visual treatment for the chart pattern — drives the chart
+ * sub-renderer (bar / line / pie / etc.). The chart "look" axis is the chart
+ * KIND, not pure visual styling. `look` is the primary surface; the legacy
+ * `chartType` prop remains as an alias.
+ *
+ * Mapping to `chartType`:
+ *  - `bar-vertical`   ↔ `bar`        (default)
+ *  - `bar-horizontal` ↔ (new)        renders bars laid out horizontally
+ *  - `line`           ↔ `line`
+ *  - `area`           ↔ `area`
+ *  - `pie`            ↔ `pie`
+ *  - `donut`          ↔ `donut`
+ *  - `scatter`        ↔ `scatter`
+ *  - `histogram`      ↔ `histogram`
+ */
+export type ChartLook = "bar-vertical" | "bar-horizontal" | "line" | "area" | "pie" | "donut" | "scatter" | "histogram";
 export type ChartStackMode = "none" | "stack" | "normalize";
 export interface ChartDataPoint {
     label: string;
@@ -46,8 +63,10 @@ export interface ChartProps {
     title?: string;
     /** Chart subtitle / description */
     subtitle?: string;
-    /** Chart type */
+    /** Chart type (legacy alias for `look`). */
     chartType?: ChartType;
+    /** Layer 2 visual treatment — drives the chart sub-renderer (bar / line / pie / etc.). */
+    look?: ChartLook;
     /** Multi-series data */
     series?: readonly ChartSeries[];
     /** Simple single-series shorthand (bar/line/pie/area/donut/histogram) */

package/dist/components/organisms/DataTable.d.ts

@@ -3,6 +3,7 @@ import type { EventKey } from "@almadar/core";
 import { LucideIcon } from "lucide-react";
 import { EntityDisplayProps } from "./types";
 import type { EntityRow } from "@almadar/core";
+export type EntityTableLook = "dense" | "spacious" | "striped" | "borderless" | "card-rows";
 export interface Column<T> {
     key: keyof T | string;
     header: string;
@@ -60,10 +61,12 @@ export interface DataTableProps<T extends EntityRow & {
     headerActions?: React.ReactNode;
     /** Show total count in pagination */
     showTotal?: boolean;
+    /** Layer 2 visual treatment — orthogonal to the semantic variant. */
+    look?: EntityTableLook;
 }
 export declare function DataTable<T extends EntityRow & {
     id: string | number;
-}>({ fields, columns, entity, itemActions, isLoading, error, emptyIcon, emptyTitle, emptyDescription, emptyAction, selectable, selectedIds, sortBy, sortDirection, searchable, searchValue, searchPlaceholder, page, pageSize, totalCount, rowActions: externalRowActions, bulkActions, headerActions, showTotal, className, }: DataTableProps<T>): import("react/jsx-runtime").JSX.Element;
+}>({ fields, columns, entity, itemActions, isLoading, error, emptyIcon, emptyTitle, emptyDescription, emptyAction, selectable, selectedIds, sortBy, sortDirection, searchable, searchValue, searchPlaceholder, page, pageSize, totalCount, rowActions: externalRowActions, bulkActions, headerActions, showTotal, className, look, }: DataTableProps<T>): import("react/jsx-runtime").JSX.Element;
 export declare namespace DataTable {
     var displayName: string;
 }

package/dist/components/organisms/Header.d.ts

@@ -6,6 +6,7 @@
  */
 import React from "react";
 import type { LucideIcon } from "lucide-react";
+export type HeaderLook = "hero" | "compact-bar" | "breadcrumb" | "contextual" | "editorial-banner";
 export interface HeaderProps {
     /**
      * Logo/Brand content
@@ -86,6 +87,8 @@ export interface HeaderProps {
      * @default 'mobile'
      */
     variant?: "mobile" | "desktop";
+    /** Layer 2 visual treatment — orthogonal to the structural variant (which currently flips mobile vs desktop). */
+    look?: HeaderLook;
     /**
      * Callback when logo/brand is clicked
      */

package/dist/components/organisms/Timeline.d.ts

@@ -15,6 +15,11 @@ import type { EventKey } from "@almadar/core";
 import type { EntityRow } from "@almadar/core";
 import type { LucideIcon } from "lucide-react";
 export type TimelineItemStatus = "complete" | "active" | "pending" | "error";
+/**
+ * Layer 2 visual treatment for the timeline pattern — orthogonal to the
+ * semantic status conveyed by per-item style.
+ */
+export type TimelineLook = "vertical-compact" | "vertical-spacious" | "horizontal" | "swimlane";
 export interface TimelineItem {
     /** Unique identifier */
     id: string;
@@ -59,5 +64,7 @@ export interface TimelineProps {
     fields: readonly string[];
     /** Actions per item */
     itemActions?: readonly TimelineAction[];
+    /** Layer 2 visual treatment. */
+    look?: TimelineLook;
 }
 export declare const Timeline: React.FC<TimelineProps>;

package/dist/docs/index.cjs

@@ -3930,6 +3930,15 @@ var shadowStyles2 = {
   md: "shadow",
   lg: "shadow-elevation-dialog"
 };
+var lookStyles = {
+  elevated: "",
+  "flat-bordered": "shadow-none border-[length:var(--border-width)] border-border",
+  "borderless-divider": "shadow-none border-0 border-b border-border rounded-none",
+  ticket: "shadow-none border-dashed border-[length:var(--border-width)] border-border",
+  invoice: "shadow-none border-[length:var(--border-width-thick)] border-border rounded-sm",
+  chip: "shadow-none rounded-pill border-[length:var(--border-width)] border-border",
+  "tile-image-first": "p-0 overflow-hidden"
+};
 var Card = React7__default.default.forwardRef(
   ({
     className,
@@ -3938,6 +3947,7 @@ var Card = React7__default.default.forwardRef(
     title,
     subtitle,
     shadow,
+    look = "elevated",
     children,
     ...props
   }, ref) => {
@@ -3950,6 +3960,7 @@ var Card = React7__default.default.forwardRef(
           "transition-all duration-[var(--transition-normal)]",
           variantStyles3[variant],
           paddingStyles2[padding],
+          lookStyles[look],
           shadow && shadowStyles2[shadow],
           className
         ),

package/dist/docs/index.d.cts

@@ -228,6 +228,11 @@ interface IconProps {
 declare const Icon: React.FC<IconProps>;
 
 type CardShadow = "none" | "sm" | "md" | "lg";
+/**
+ * Layer 2 visual treatment for the card pattern — orthogonal to the semantic
+ * `variant` (which conveys role / state).
+ */
+type CardLook = "elevated" | "flat-bordered" | "borderless-divider" | "ticket" | "invoice" | "chip" | "tile-image-first";
 interface CardProps extends React.HTMLAttributes<HTMLDivElement> {
     variant?: "default" | "bordered" | "elevated" | "interactive";
     padding?: "none" | "sm" | "md" | "lg";
@@ -237,6 +242,8 @@ interface CardProps extends React.HTMLAttributes<HTMLDivElement> {
     subtitle?: string;
     /** Shadow size override */
     shadow?: CardShadow;
+    /** Layer 2 visual treatment — orthogonal to the semantic variant. */
+    look?: CardLook;
     /** Card content */
     children?: React.ReactNode;
 }

package/dist/docs/index.js

@@ -3903,6 +3903,15 @@ var shadowStyles2 = {
   md: "shadow",
   lg: "shadow-elevation-dialog"
 };
+var lookStyles = {
+  elevated: "",
+  "flat-bordered": "shadow-none border-[length:var(--border-width)] border-border",
+  "borderless-divider": "shadow-none border-0 border-b border-border rounded-none",
+  ticket: "shadow-none border-dashed border-[length:var(--border-width)] border-border",
+  invoice: "shadow-none border-[length:var(--border-width-thick)] border-border rounded-sm",
+  chip: "shadow-none rounded-pill border-[length:var(--border-width)] border-border",
+  "tile-image-first": "p-0 overflow-hidden"
+};
 var Card = React7.forwardRef(
   ({
     className,
@@ -3911,6 +3920,7 @@ var Card = React7.forwardRef(
     title,
     subtitle,
     shadow,
+    look = "elevated",
     children,
     ...props
   }, ref) => {
@@ -3923,6 +3933,7 @@ var Card = React7.forwardRef(
           "transition-all duration-[var(--transition-normal)]",
           variantStyles3[variant],
           paddingStyles2[padding],
+          lookStyles[look],
           shadow && shadowStyles2[shadow],
           className
         ),

package/dist/marketing/index.cjs

@@ -4014,6 +4014,15 @@ var shadowStyles2 = {
   md: "shadow",
   lg: "shadow-elevation-dialog"
 };
+var lookStyles = {
+  elevated: "",
+  "flat-bordered": "shadow-none border-[length:var(--border-width)] border-border",
+  "borderless-divider": "shadow-none border-0 border-b border-border rounded-none",
+  ticket: "shadow-none border-dashed border-[length:var(--border-width)] border-border",
+  invoice: "shadow-none border-[length:var(--border-width-thick)] border-border rounded-sm",
+  chip: "shadow-none rounded-pill border-[length:var(--border-width)] border-border",
+  "tile-image-first": "p-0 overflow-hidden"
+};
 var Card = React8__default.default.forwardRef(
   ({
     className,
@@ -4022,6 +4031,7 @@ var Card = React8__default.default.forwardRef(
     title,
     subtitle,
     shadow,
+    look = "elevated",
     children,
     ...props
   }, ref) => {
@@ -4034,6 +4044,7 @@ var Card = React8__default.default.forwardRef(
           "transition-all duration-[var(--transition-normal)]",
           variantStyles4[variant],
           paddingStyles2[padding],
+          lookStyles[look],
           shadow && shadowStyles2[shadow],
           className
         ),

package/dist/marketing/index.d.cts

@@ -250,6 +250,11 @@ interface IconProps {
 declare const Icon: React.FC<IconProps>;
 
 type CardShadow = "none" | "sm" | "md" | "lg";
+/**
+ * Layer 2 visual treatment for the card pattern — orthogonal to the semantic
+ * `variant` (which conveys role / state).
+ */
+type CardLook = "elevated" | "flat-bordered" | "borderless-divider" | "ticket" | "invoice" | "chip" | "tile-image-first";
 interface CardProps extends React.HTMLAttributes<HTMLDivElement> {
     variant?: "default" | "bordered" | "elevated" | "interactive";
     padding?: "none" | "sm" | "md" | "lg";
@@ -259,6 +264,8 @@ interface CardProps extends React.HTMLAttributes<HTMLDivElement> {
     subtitle?: string;
     /** Shadow size override */
     shadow?: CardShadow;
+    /** Layer 2 visual treatment — orthogonal to the semantic variant. */
+    look?: CardLook;
     /** Card content */
     children?: React.ReactNode;
 }

package/dist/marketing/index.js

@@ -3987,6 +3987,15 @@ var shadowStyles2 = {
   md: "shadow",
   lg: "shadow-elevation-dialog"
 };
+var lookStyles = {
+  elevated: "",
+  "flat-bordered": "shadow-none border-[length:var(--border-width)] border-border",
+  "borderless-divider": "shadow-none border-0 border-b border-border rounded-none",
+  ticket: "shadow-none border-dashed border-[length:var(--border-width)] border-border",
+  invoice: "shadow-none border-[length:var(--border-width-thick)] border-border rounded-sm",
+  chip: "shadow-none rounded-pill border-[length:var(--border-width)] border-border",
+  "tile-image-first": "p-0 overflow-hidden"
+};
 var Card = React8.forwardRef(
   ({
     className,
@@ -3995,6 +4004,7 @@ var Card = React8.forwardRef(
     title,
     subtitle,
     shadow,
+    look = "elevated",
     children,
     ...props
   }, ref) => {
@@ -4007,6 +4017,7 @@ var Card = React8.forwardRef(
           "transition-all duration-[var(--transition-normal)]",
           variantStyles4[variant],
           paddingStyles2[padding],
+          lookStyles[look],
           shadow && shadowStyles2[shadow],
           className
         ),