@gridui/branding 0.0.0-stage → 0.0.0

package/README.md

@@ -1,3 +1,45 @@
-# Temporary Holding Version
+# @gridui/branding
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Layout family. `Branding` and `BrandingItem` arrange any number of differently
+proportioned brand items inside a consumer-positioned region. Full-width and
+bottom-corner modes apply within that region. Each incomplete row expands its
+final cell while preserving artwork proportions.
+
+The package owns its item geometry and seams. It does not depend on Grid or
+SiteFooter. Consumers own placement in the page, region dimensions, brand assets,
+links, and accessible names. Related component parts share this package; users
+can install its behavior and styles independently of other layout families.
+
+## Install
+
+```sh
+pnpm add @gridui/branding @gridui/theme
+```
+
+Use compatible React 19 and React DOM 19 in the consuming application.
+Load Theme before this package's stylesheet. No application Tailwind build is
+required.
+
+```tsx
+import { Branding, BrandingItem } from "@gridui/branding";
+import "@gridui/theme/styles.css";
+import "@gridui/branding/styles.css";
+
+<Branding placement="bottom-left" itemHeight={48} style={{ minHeight: 160 }}>
+    <BrandingItem asChild aspectRatio={1}>
+        <a href="/" aria-label="Home"><img src="/symbol.svg" alt="" /></a>
+    </BrandingItem>
+    <BrandingItem asChild aspectRatio={7.06}>
+        <a href="/about"><img src="/wordmark.svg" alt="Our studio" /></a>
+    </BrandingItem>
+</Branding>
+```
+
+Read the [branding contract](docs/guides/branding.md) for alignment, container-driven
+wrapping, frame ownership, native links, and hydration behavior.
+[Component reference](docs/reference/README.md) lists the public Props contracts.
+The package-owned [Storybook examples](https://github.com/sudo-ui/GridUI-React-Monorepo/blob/main/packages-layout/branding/stories/branding.stories.tsx) provide
+adjustable item counts, aspect ratios, cell widths, and placement.
+
+See [component ownership](https://github.com/sudo-ui/GridUI-React-Monorepo/blob/main/docs/component-ownership.md)
+and [release history](https://github.com/sudo-ui/GridUI-React-Monorepo/tree/main/packages-layout/branding/.changeset/history).

package/dist/branding/branding.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @author WMXPY
+ * @package Branding
+ * @namespace Branding
+ * @description Branding
+ */
+import { type ComponentPropsWithRef, type FC } from "react";
+export type BrandingProps = ComponentPropsWithRef<"div"> & {
+    readonly placement?: "full" | "bottom-left" | "bottom-right";
+    readonly itemHeight?: number;
+    readonly frame?: "all" | "internal" | "none";
+};
+export declare const Branding: FC<BrandingProps>;

package/dist/branding-item/branding-item.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @author WMXPY
+ * @package Branding
+ * @namespace BrandingItem
+ * @description Branding Item
+ */
+import type { ComponentPropsWithRef, FC } from "react";
+export type BrandingItemProps = ComponentPropsWithRef<"div"> & {
+    readonly asChild?: boolean;
+    readonly aspectRatio?: number;
+};
+export declare const BrandingItem: FC<BrandingItemProps>;

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @author WMXPY
+ * @package Branding
+ * @namespace Root
+ * @description Index
+ */
+export type { BrandingProps } from "./branding/branding";
+export { Branding } from "./branding/branding";
+export type { BrandingItemProps } from "./branding-item/branding-item";
+export { BrandingItem } from "./branding-item/branding-item";

package/dist/index.js

@@ -0,0 +1,138 @@
+// src/branding-item/branding-item.tsx
+import { cn } from "@gridui/style-utils";
+import { Slot } from "@radix-ui/react-slot";
+import { jsx } from "react/jsx-runtime";
+var BrandingItem = (props) => {
+  const { asChild = false, aspectRatio = 1, className, style, ...restProps } = props;
+  if (!Number.isFinite(aspectRatio) || aspectRatio <= 0) {
+    throw new RangeError("BrandingItem aspectRatio must be a positive finite number.");
+  }
+  const layoutStyle = {
+    "--gridui-branding-item-width": `calc(var(--gridui-branding-height, 48px) * ${aspectRatio})`,
+    ...style
+  };
+  const Component = asChild ? Slot : "div";
+  return /* @__PURE__ */ jsx(
+    Component,
+    {
+      ...restProps,
+      className: cn("gridui-branding-item", className),
+      style: layoutStyle
+    }
+  );
+};
+
+// src/branding/branding.tsx
+import { cn as cn2 } from "@gridui/style-utils";
+import { Children, cloneElement, isValidElement, useLayoutEffect, useRef, useState } from "react";
+import { jsx as jsx2 } from "react/jsx-runtime";
+var Branding = (props) => {
+  const {
+    placement = "bottom-left",
+    itemHeight = 48,
+    frame = "all",
+    children,
+    className,
+    style,
+    ...restProps
+  } = props;
+  const strip = useRef(null);
+  const [
+    rows,
+    setRows
+  ] = useState([]);
+  useLayoutEffect(() => {
+    const element = strip.current;
+    if (!element) {
+      return;
+    }
+    const measureRows = () => {
+      let row = 0;
+      let previousTop;
+      const next = Array.from(element.children, (item) => {
+        const top = item.getBoundingClientRect().top;
+        if (previousTop !== void 0 && top !== previousTop) {
+          row += 1;
+        }
+        previousTop = top;
+        return row;
+      });
+      setRows((current) => {
+        return current.length === next.length && current.every((value, index) => {
+          return value === next[index];
+        }) ? current : next;
+      });
+    };
+    const observer = new ResizeObserver(measureRows);
+    observer.observe(element);
+    for (const item of element.children) {
+      observer.observe(item);
+    }
+    measureRows();
+    return () => {
+      observer.disconnect();
+    };
+  }, [
+    children,
+    itemHeight,
+    frame
+  ]);
+  if (!Number.isFinite(itemHeight) || itemHeight <= 0) {
+    throw new RangeError("Branding itemHeight must be a positive finite number.");
+  }
+  const items = Children.toArray(children).map((child) => {
+    if (!isValidElement(child) || child.type !== BrandingItem) {
+      throw new TypeError("Branding requires direct BrandingItem children.");
+    }
+    return child;
+  });
+  const sizes = items.map((item) => {
+    const size = itemHeight * (item.props.aspectRatio ?? 1);
+    if (!Number.isFinite(size) || size <= 0) {
+      throw new RangeError("BrandingItem aspectRatio must be a positive finite number.");
+    }
+    return size;
+  });
+  const layoutStyle = {
+    "--gridui-branding-height": `${itemHeight}px`,
+    "--gridui-branding-width": `${sizes.reduce((sum, size) => {
+      return sum + size;
+    }, 0)}px`,
+    ...style
+  };
+  return /* @__PURE__ */ jsx2(
+    "div",
+    {
+      ...restProps,
+      className: cn2("gridui-branding", className),
+      style: layoutStyle,
+      "data-placement": placement,
+      children: /* @__PURE__ */ jsx2(
+        "div",
+        {
+          ref: strip,
+          className: cn2("gridui-branding-strip"),
+          "data-frame": frame,
+          children: items.map((item, index) => {
+            const itemStyle = {
+              "--gridui-branding-item-width": `${sizes[index]}px`,
+              ...item.props.style
+            };
+            return cloneElement(item, {
+              style: itemStyle,
+              ...{
+                "data-row-end": rows[index] !== rows[index + 1] || void 0,
+                "data-last-row": rows[index] === rows.at(-1) || void 0
+              }
+            });
+          })
+        }
+      )
+    }
+  );
+};
+export {
+  Branding,
+  BrandingItem
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/branding-item/branding-item.tsx", "../src/branding/branding.tsx"],
+  "sourcesContent": ["/**\n * @author WMXPY\n * @package Branding\n * @namespace BrandingItem\n * @description Branding Item\n */\n\nimport type { LayoutStyle } from \"../shared/types\";\nimport { cn } from \"@gridui/style-utils\";\nimport { Slot } from \"@radix-ui/react-slot\";\nimport type { ComponentPropsWithRef, FC } from \"react\";\n\nexport type BrandingItemProps = ComponentPropsWithRef<\"div\"> & {\n    readonly asChild?: boolean;\n    readonly aspectRatio?: number;\n};\n\nexport const BrandingItem: FC<BrandingItemProps> = (props: BrandingItemProps) => {\n    const { asChild = false, aspectRatio = 1, className, style, ...restProps } = props;\n    if (!Number.isFinite(aspectRatio) || aspectRatio <= 0) {\n        throw new RangeError(\"BrandingItem aspectRatio must be a positive finite number.\");\n    }\n    const layoutStyle: LayoutStyle = {\n        \"--gridui-branding-item-width\": `calc(var(--gridui-branding-height, 48px) * ${aspectRatio})`,\n        ...style,\n    };\n    const Component = asChild ? Slot : \"div\";\n    return (<Component\n        {...restProps}\n        className={cn(\"gridui-branding-item\", className)}\n        style={layoutStyle}\n    />);\n};\n", "/**\n * @author WMXPY\n * @package Branding\n * @namespace Branding\n * @description Branding\n */\n\nimport { BrandingItem, type BrandingItemProps } from \"../branding-item/branding-item\";\nimport type { LayoutStyle } from \"../shared/types\";\nimport { cn } from \"@gridui/style-utils\";\nimport { Children, cloneElement, type ComponentPropsWithRef, type FC, isValidElement, useLayoutEffect, useRef, useState } from \"react\";\n\nexport type BrandingProps = ComponentPropsWithRef<\"div\"> & {\n    readonly placement?: \"full\" | \"bottom-left\" | \"bottom-right\";\n    readonly itemHeight?: number;\n    readonly frame?: \"all\" | \"internal\" | \"none\";\n};\n\nexport const Branding: FC<BrandingProps> = (props: BrandingProps) => {\n    const {\n        placement = \"bottom-left\",\n        itemHeight = 48,\n        frame = \"all\",\n        children,\n        className,\n        style,\n        ...restProps\n    } = props;\n    const strip = useRef<HTMLDivElement>(null);\n    const [\n        rows,\n        setRows,\n    ] = useState<readonly number[]>([]);\n    useLayoutEffect(() => {\n        const element = strip.current;\n        if (!element) {\n            return;\n        }\n        const measureRows = (): void => {\n            let row = 0;\n            let previousTop: number | undefined;\n            const next = Array.from(element.children, (item) => {\n                const top = item.getBoundingClientRect().top;\n                if (previousTop !== undefined && top !== previousTop) {\n                    row += 1;\n                }\n                previousTop = top;\n                return row;\n            });\n            setRows(current => {\n                return current.length === next.length && current.every((value, index) => {\n                    return value === next[index];\n                }) ? current : next;\n            });\n        };\n        // Native flex layout owns wrapping, including padding, borders and rounding.\n        const observer = new ResizeObserver(measureRows);\n        observer.observe(element);\n        for (const item of element.children) {\n            observer.observe(item);\n        }\n        measureRows();\n        return () => {\n            observer.disconnect();\n        };\n    }, [\n        children,\n        itemHeight,\n        frame,\n    ]);\n    if (!Number.isFinite(itemHeight) || itemHeight <= 0) {\n        throw new RangeError(\"Branding itemHeight must be a positive finite number.\");\n    }\n    const items = Children.toArray(children).map((child) => {\n        if (!isValidElement<BrandingItemProps>(child) || child.type !== BrandingItem) {\n            throw new TypeError(\"Branding requires direct BrandingItem children.\");\n        }\n        return child;\n    });\n    const sizes = items.map((item) => {\n        const size = itemHeight * (item.props.aspectRatio ?? 1);\n        if (!Number.isFinite(size) || size <= 0) {\n            throw new RangeError(\"BrandingItem aspectRatio must be a positive finite number.\");\n        }\n        return size;\n    });\n    const layoutStyle: LayoutStyle = {\n        \"--gridui-branding-height\": `${itemHeight}px`,\n        \"--gridui-branding-width\": `${sizes.reduce((sum, size) => {\n            return sum + size;\n        }, 0)}px`,\n        ...style,\n    };\n    return (<div\n        {...restProps}\n        className={cn(\"gridui-branding\", className)}\n        style={layoutStyle}\n        data-placement={placement}\n    >\n        <div\n            ref={strip}\n            className={cn(\"gridui-branding-strip\")}\n            data-frame={frame}\n        >\n            {items.map((item, index) => {\n                const itemStyle: LayoutStyle = {\n                    \"--gridui-branding-item-width\": `${sizes[index]}px`,\n                    ...item.props.style,\n                };\n                return cloneElement(item, {\n                    style: itemStyle,\n                    ...{\n                        \"data-row-end\": rows[index] !== rows[index + 1] || undefined,\n                        \"data-last-row\": rows[index] === rows.at(-1) || undefined,\n                    },\n                });\n            })}\n        </div>\n    </div>);\n};\n"],
+  "mappings": "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",
+  "names": ["cn", "jsx"]
+}

package/dist/shared/types.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @author WMXPY
+ * @package Branding
+ * @namespace Shared
+ * @description Types
+ */
+import type { CSSProperties } from "react";
+export type LayoutStyle = CSSProperties & {
+    [key: `--gridui-${string}`]: string | number;
+};

package/dist/styles.css

@@ -0,0 +1,69 @@
+/*! tailwindcss v4.3.5 | MIT License | https://tailwindcss.com */
+@layer theme, base, components, utilities;
+@layer utilities;
+@layer components {
+  .gridui-branding {
+    display: flex;
+    align-items: flex-end;
+    justify-content: left;
+    width: 100%;
+    height: 100%;
+    min-width: 0;
+  }
+  .gridui-branding[data-placement="bottom-right"] {
+    justify-content: right;
+  }
+  .gridui-branding-strip {
+    display: flex;
+    flex-wrap: wrap;
+    box-sizing: border-box;
+    width: min(100%, var(--gridui-branding-width));
+    min-width: 0;
+  }
+  .gridui-branding[data-placement="full"] > .gridui-branding-strip {
+    width: 100%;
+  }
+  .gridui-branding-strip[data-frame="all"]:not(:empty) {
+    width: min(100%, calc(var(--gridui-branding-width) + 1px));
+    border-top: 1px solid var(--gridui-border);
+    border-inline-start: 1px solid var(--gridui-border);
+  }
+  .gridui-branding[data-placement="full"] > .gridui-branding-strip[data-frame="all"] {
+    width: 100%;
+  }
+  .gridui-branding-strip[data-frame="all"] > .gridui-branding-item, .gridui-branding-strip[data-frame="internal"] > .gridui-branding-item {
+    border-inline-end: 1px solid var(--gridui-border);
+    border-bottom: 1px solid var(--gridui-border);
+  }
+  .gridui-branding-strip[data-frame="internal"] > .gridui-branding-item[data-row-end] {
+    border-inline-end-color: transparent;
+  }
+  .gridui-branding-strip[data-frame="internal"] > .gridui-branding-item[data-last-row] {
+    border-bottom-color: transparent;
+  }
+  .gridui-branding-item {
+    position: relative;
+    display: flex;
+    flex: 0 0 min(100%, var(--gridui-branding-item-width));
+    align-items: center;
+    justify-content: center;
+    box-sizing: border-box;
+    min-width: 0;
+    height: var(--gridui-branding-height, 48px);
+    padding: var(--gridui-space-8);
+    color: inherit;
+    overflow-wrap: anywhere;
+    text-decoration: none;
+  }
+  .gridui-branding-item[data-row-end], .gridui-branding-item:last-child {
+    flex-grow: 1;
+  }
+  .gridui-branding-item > :is(img, svg) {
+    width: 100%;
+    height: 100%;
+    object-fit: contain;
+  }
+  .gridui-branding-item:is(:focus-visible, :has(:focus-visible)) {
+    z-index: var(--gridui-z-interaction);
+  }
+}

package/docs/README.md

@@ -0,0 +1,7 @@
+# Branding guides
+
+Read [Branding cells](guides/branding.md) for the layout and composition contract.
+[Public API reference](reference/README.md) lists the exported component signatures.
+
+Branding has its own stylesheet and does not require Grid or SiteFooter. Load
+`@gridui/theme/styles.css` before `@gridui/branding/styles.css`.

package/docs/catalog.json

@@ -0,0 +1,47 @@
+{
+  "schemaVersion": 1,
+  "name": "@gridui/branding",
+  "version": "0.0.0",
+  "category": "layout",
+  "description": "GridUI React branding cells",
+  "usage": "Layout family. `Branding` and `BrandingItem` arrange any number of differently proportioned brand items inside a consumer-positioned region. Full-width and bottom-corner modes apply within that region. Each incomplete row expands its final cell while preserving artwork proportions.",
+  "documentation": [
+    "README.md",
+    "docs/README.md",
+    "docs/guides/branding.md",
+    "docs/reference/README.md",
+    "docs/reference/branding-item.md",
+    "docs/reference/branding.md"
+  ],
+  "exports": [
+    {
+      "name": "Branding",
+      "kind": "component",
+      "importPath": "@gridui/branding"
+    },
+    {
+      "name": "BrandingItem",
+      "kind": "component",
+      "importPath": "@gridui/branding"
+    },
+    {
+      "name": "BrandingItemProps",
+      "kind": "type",
+      "importPath": "@gridui/branding"
+    },
+    {
+      "name": "BrandingProps",
+      "kind": "type",
+      "importPath": "@gridui/branding"
+    }
+  ],
+  "styles": [
+    "@gridui/theme/styles.css",
+    "@gridui/branding/styles.css"
+  ],
+  "examples": [
+    "https://github.com/sudo-ui/GridUI-React-Monorepo/blob/main/packages-layout/branding/stories/branding.mdx",
+    "https://github.com/sudo-ui/GridUI-React-Monorepo/blob/main/packages-layout/branding/stories/getting-started.mdx",
+    "https://github.com/sudo-ui/GridUI-React-Monorepo/blob/main/packages-layout/branding/stories/branding.stories.tsx"
+  ]
+}

package/docs/guides/branding.md

@@ -0,0 +1,62 @@
+# Branding cells
+
+`Branding` arranges any number of differently proportioned `BrandingItem` cells.
+The consumer places and sizes the branding region. It can accompany a footer but
+has no footer dependency, fixed page position, routes, assets, or required brands.
+
+```tsx
+import { Branding, BrandingItem } from "@gridui/branding";
+
+<Branding placement="bottom-left" itemHeight={48} style={{ minHeight: 160 }}>
+    <BrandingItem asChild aspectRatio={1}>
+        <a href="/" aria-label="Home"><img src="/symbol.svg" alt="" /></a>
+    </BrandingItem>
+    <BrandingItem asChild aspectRatio={7.06}>
+        <a href="/about"><img src="/wordmark.svg" alt="Our studio" /></a>
+    </BrandingItem>
+</Branding>
+```
+
+- `placement`: `bottom-left` (default), `bottom-right`, or `full`. Corner modes
+  use the items' preferred total width up to the cell width. Full mode uses the
+  complete cell width. All three align to the bottom of the allocated region;
+  assign a height or min-height when spare vertical space is needed.
+- `itemHeight`: positive finite row height in pixels, default `48`.
+- `BrandingItem aspectRatio`: positive finite preferred cell width / height,
+  default `1`. Item width starts at `itemHeight * aspectRatio`. Item padding is
+  the shared 8px token. Direct images and SVGs fit within the resulting cell
+  without distortion; custom nested content owns its own sizing.
+- `frame`: `all` (default) owns the perimeter and one-pixel seams, `internal`
+  owns only seams, and `none` draws no lines.
+
+Rows follow native flex wrapping; ResizeObserver identifies the actual row ends,
+including padding, borders, and fractional pixel rounding. Like Grid's
+`fillLastRow`, the final item of **each** incomplete row expands to fill the row;
+other item widths retain their preferred size, subject to their padding and border
+minimum. Oversized items clamp to the row width.
+Artwork retains its proportions when its cell expands or shrinks. No item count
+or common artwork shape is prescribed. Before measurement, CSS flex wrapping
+keeps items within the cell and the final item fills remaining space.
+
+Pass direct BrandingItem children, including arrays and conditional children.
+Use `asChild` on items for full-cell native links; supply an accessible name.
+Stable keys retain DOM identity and keyboard focus during reflow. Use conditional
+children to remove items from layout. Empty branding renders no frame. The root
+forwards native div attributes and ref; each item forwards native attributes and
+ref to its div or slotted host. The component does not create a landmark.
+
+## Compose real brand resources
+
+The Storybook Two brands and Three brands compositions combine `Logo` from
+`@gridui/gridui-brand`, `SudosaurusWordmark` from `@sudosaurus/sudosaurus-logo`,
+and an optional Lucide `Sparkles` icon. GridUI and Lucide use square artwork;
+Sudosaurus takes the remaining width. The wordmark's consumer-owned flex style
+allows it to shrink to one ordinary cell width before wrapping, preventing larger
+icons from squeezing the wordmark to zero. After wrapping, the final cell fills
+the row while artwork retains its proportions. The preferred aspect ratio determines
+the natural width for corner placement. Its font size follows the available cell
+width and height; proportional letter spacing preserves the wordmark geometry.
+
+Import each brand's optional motion stylesheet in the consuming composition.
+These packages are development dependencies for the examples, not runtime
+dependencies of Branding. See the [working composition](https://github.com/sudo-ui/GridUI-React-Monorepo/blob/main/packages-layout/branding/stories/brand-resources-example.tsx).

package/docs/reference/README.md

@@ -0,0 +1,5 @@
+<!-- Generated by pnpm docs:storybook. -->
+# Component reference
+
+- [Branding](branding.md)
+- [BrandingItem](branding-item.md)

package/docs/reference/branding-item.md

@@ -0,0 +1,69 @@
+<!-- Generated from public Props and owned stories. Run pnpm docs:storybook. -->
+# BrandingItem
+
+Compose BrandingItem with Branding inside the same @gridui/branding component family.
+
+Import from ``@gridui/branding`` and load Theme before this family's stylesheet.
+
+```tsx
+import { BrandingItem } from "@gridui/branding";
+import "@gridui/theme/styles.css";
+import "@gridui/branding/styles.css";
+```
+
+Read the [package contract](https://github.com/sudo-ui/GridUI-React-Monorepo/blob/main/packages-layout/branding/README.md) for shared behavior and stylesheet dependencies.
+
+The [working composition](https://github.com/sudo-ui/GridUI-React-Monorepo/blob/main/packages-layout/branding/stories/branding.stories.tsx) demonstrates required context, state, and related components. Use View code in Storybook to inspect the actual implementation.
+
+## API
+
+The public Props type is the source of these signatures. Defaults below are explicit implementation defaults; story presets are separate. Native attributes remain available through the exported Props type.
+
+### children
+
+``ReactNode`` · Optional
+
+Content rendered inside the component.
+
+### onFocus
+
+``(event: FocusEvent<HTMLDivElement, Element>): void`` · Optional
+
+Called when the corresponding interaction occurs; inspect the arguments in Actions.
+
+### onBlur
+
+``(event: FocusEvent<HTMLDivElement, Element>): void`` · Optional
+
+Called when the corresponding interaction occurs; inspect the arguments in Actions.
+
+### onChange
+
+``(event: ChangeEvent<HTMLDivElement, Element>): void`` · Optional
+
+Called when the corresponding interaction occurs; inspect the arguments in Actions.
+
+### onSubmit
+
+``(event: SubmitEvent<HTMLDivElement>): void`` · Optional
+
+Called when the corresponding interaction occurs; inspect the arguments in Actions.
+
+### onClick
+
+``(event: MouseEvent<HTMLDivElement, MouseEvent>): void`` · Optional
+
+Called when the corresponding interaction occurs; inspect the arguments in Actions.
+
+### asChild
+
+``boolean | undefined`` · Optional
+
+Default: ``false``
+
+### aspectRatio
+
+``number | undefined`` · Optional
+
+Default: ``1``
+

package/docs/reference/branding.md

@@ -0,0 +1,75 @@
+<!-- Generated from public Props and owned stories. Run pnpm docs:storybook. -->
+# Branding
+
+Arranges brand items inside a consumer-positioned cell. Choose full width or either bottom corner; each incomplete row extends its final item without stretching its artwork.
+
+Import from ``@gridui/branding`` and load Theme before this family's stylesheet.
+
+```tsx
+import { Branding } from "@gridui/branding";
+import "@gridui/theme/styles.css";
+import "@gridui/branding/styles.css";
+```
+
+Read the [package contract](https://github.com/sudo-ui/GridUI-React-Monorepo/blob/main/packages-layout/branding/README.md) for shared behavior and stylesheet dependencies.
+
+The [working composition](https://github.com/sudo-ui/GridUI-React-Monorepo/blob/main/packages-layout/branding/stories/branding.stories.tsx) demonstrates required context, state, and related components. Use View code in Storybook to inspect the actual implementation.
+
+## API
+
+The public Props type is the source of these signatures. Defaults below are explicit implementation defaults; story presets are separate. Native attributes remain available through the exported Props type.
+
+### children
+
+``ReactNode`` · Optional
+
+Content rendered inside the component.
+
+### onFocus
+
+``(event: FocusEvent<HTMLDivElement, Element>): void`` · Optional
+
+Called when the corresponding interaction occurs; inspect the arguments in Actions.
+
+### onBlur
+
+``(event: FocusEvent<HTMLDivElement, Element>): void`` · Optional
+
+Called when the corresponding interaction occurs; inspect the arguments in Actions.
+
+### onChange
+
+``(event: ChangeEvent<HTMLDivElement, Element>): void`` · Optional
+
+Called when the corresponding interaction occurs; inspect the arguments in Actions.
+
+### onSubmit
+
+``(event: SubmitEvent<HTMLDivElement>): void`` · Optional
+
+Called when the corresponding interaction occurs; inspect the arguments in Actions.
+
+### onClick
+
+``(event: MouseEvent<HTMLDivElement, MouseEvent>): void`` · Optional
+
+Called when the corresponding interaction occurs; inspect the arguments in Actions.
+
+### placement
+
+``"full" | "bottom-left" | "bottom-right" | undefined`` · Optional
+
+Default: ``"bottom-left"``
+
+### itemHeight
+
+``number | undefined`` · Optional
+
+Default: ``48``
+
+### frame
+
+``"none" | "all" | "internal" | undefined`` · Optional
+
+Default: ``"all"``
+

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@gridui/branding",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.0",
+  "description": "GridUI React branding cells",
+  "license": "UNLICENSED",
+  "type": "module",
+  "files": [
+    "dist",
+    "docs",
+    "README.md"
+  ],
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./styles.css": "./dist/styles.css"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@gridui/style-utils": "^4.0.0",
+    "@gridui/theme": "^2.5.4",
+    "@radix-ui/react-slot": "1.5.0"
+  },
+  "devDependencies": {
+    "@gridui-internal/configuration": "0.0.0-internal",
+    "@gridui/gridui-brand": "0.0.0",
+    "@jest/globals": "30.5.2",
+    "@storybook/react-vite": "10.6.7",
+    "@sudosaurus/sudosaurus-logo": "1.0.0",
+    "@types/jest": "30.0.0",
+    "@types/node": "26.6.6",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "jest": "30.5.2",
+    "lucide-react": "1.71.0",
+    "react": "19.3.1",
+    "react-dom": "19.3.1",
+    "typescript": "6.0.3"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "scripts": {
+    "build": "node ../../scripts/compilation/package.ts",
+    "compile": "tsc --project tsconfig.json",
+    "test": "jest",
+    "coverage": "jest --coverage"
+  }
 }