brand-shell 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Venkatesh Bommadevara
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,316 @@
+## Brand Shell
+
+Reusable header and footer components that ship with a premium default theme, typed props, and Storybook-based docs. Drop the package into React, Next.js, TanStack Router, Vue, or Svelte apps to keep your brand chrome consistent across projects.
+
+### Installation
+
+```bash
+bun add brand-shell
+```
+
+### Basic usage
+
+```tsx
+import { Header, Footer, type BrandDetails, type BrandTheme } from "brand-shell";
+import "brand-shell/default.css";
+
+const details: BrandDetails = {
+  name: "Mounika Thota",
+  homeHref: "/",
+  navLinks: [
+    { label: "Blog", href: "/blog" },
+    { label: "Docs", href: "/docs" },
+  ],
+  primaryAction: { label: "Hire Me", href: "mailto:hello@example.com" },
+  secondaryAction: { label: "Resume", href: "/resume.pdf", target: "_blank" },
+  linkedin: "https://linkedin.com/in/example",
+  github: "https://github.com/example",
+  twitter: "https://twitter.com/example",
+  gmail: "hello@example.com",
+  tagline: "Design-system quality shell for every project.",
+};
+
+const theme: BrandTheme = {
+  primaryColor: "#0ea5e9",
+  backgroundColor: "#0f172a",
+  textColor: "#f8fafc",
+  fontFamily: '"Inter", system-ui, sans-serif',
+  socialIconSize: "2.25rem",
+};
+
+export function Layout({ children }: { children: React.ReactNode }) {
+  return (
+    <>
+      <Header details={details} theme={theme} />
+      {children}
+      <Footer details={details} theme={theme} />
+    </>
+  );
+}
+```
+
+### Framework-agnostic core helpers
+
+The package now exports pure TypeScript helpers you can reuse in other framework adapters:
+
+```ts
+import {
+  buildShellViewModel,
+  validateBrandDetails,
+  validateBrandTheme,
+} from "brand-shell";
+```
+
+`buildShellViewModel` normalizes nav links and CTA behavior (target/rel/variants) so framework adapters share the same rules.
+
+Validation + normalization are also exported for external integrations. The adapters run these checks in development mode.
+
+```ts
+const detailsCheck = validateBrandDetails(input.details);
+const themeCheck = validateBrandTheme(input.theme);
+
+if (!detailsCheck.valid || !themeCheck.valid) {
+  throw new Error([...detailsCheck.errors, ...themeCheck.errors].join("\n"));
+}
+
+const normalizedDetails = detailsCheck.normalized;
+const normalizedTheme = themeCheck.normalized;
+```
+
+### JSON schema
+
+You can validate payloads in any runtime using the published schema:
+
+```ts
+import schema from "brand-shell/schema";
+// also available as: brand-shell/schema.json
+```
+
+This repo validates the schema with Ajv in unit tests (`src/core/schema.test.ts`) to catch contract regressions before release.
+
+Package publish surface is also guarded by `bun run pack:check` (allowed files + unpacked size budget) so docs/dev-webapp files cannot bloat the npm package.
+
+### Web Components adapter
+
+You can also use framework-agnostic custom elements:
+
+```ts
+import { applyBrandShellProps, registerBrandShellElements } from "brand-shell/web";
+import "brand-shell/default.css";
+
+registerBrandShellElements();
+```
+
+```html
+<brand-header id="app-header"></brand-header>
+<brand-footer id="app-footer"></brand-footer>
+```
+
+```ts
+const details = {
+  name: "Brand Shell",
+  homeHref: "/",
+  navLinks: [{ label: "Docs", href: "/docs" }],
+  primaryAction: { label: "Contact", href: "mailto:hello@example.com" },
+  linkedin: "https://linkedin.com/in/example",
+};
+
+const theme = {
+  primaryColor: "#0ea5e9",
+  backgroundColor: "#0f172a",
+  textColor: "#f8fafc",
+};
+
+const header = document.getElementById("app-header");
+const footer = document.getElementById("app-footer");
+
+if (header && footer) {
+  applyBrandShellProps(header, { details, theme });
+  applyBrandShellProps(footer, { details, theme });
+}
+```
+
+### Vue adapter
+
+Use framework-native Vue components:
+
+```vue
+<script setup>
+import { BrandFooter, BrandHeader } from "brand-shell/vue";
+import "brand-shell/default.css";
+
+const details = { name: "Brand Shell" };
+const theme = { primaryColor: "#0ea5e9" };
+</script>
+
+<template>
+  <BrandHeader :details="details" :theme="theme" />
+  <BrandFooter :details="details" :theme="theme" />
+</template>
+```
+
+### Svelte adapter
+
+Use a Svelte action on the custom element tags:
+
+```svelte
+<script>
+  import { brandShell } from "brand-shell/svelte";
+  import "brand-shell/default.css";
+
+  const shellProps = {
+    details: { name: "Brand Shell" },
+    theme: { primaryColor: "#0ea5e9" },
+  };
+</script>
+
+<brand-header use:brandShell={shellProps}></brand-header>
+<brand-footer use:brandShell={shellProps}></brand-footer>
+```
+
+### Props reference
+
+#### `BrandDetails`
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `name` | `string` | Required brand name shown in header/footer |
+| `homeHref` | `string` | Optional link applied to the header name/logo |
+| `navLinks` | `BrandNavLink[]` | Optional text links (e.g. Blog, Docs, About) |
+| `primaryAction` | `BrandAction` | Highlighted CTA button (e.g. Hire me) |
+| `secondaryAction` | `BrandAction` | Optional secondary CTA button |
+| `linkedin`, `github`, `twitter`, `discord`, `website` | `string` | Social/profile URLs rendered as icon buttons |
+| `gmail` | `string` | Email address or `mailto:` link |
+| `tagline` | `string` | Short line shown in the footer |
+
+#### `BrandNavLink`
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `label` | `string` | Visible text |
+| `href` | `string` | Destination |
+| `ariaLabel` | `string` | Optional accessible label override |
+| `target` | `_blank \| _self \| _parent \| _top` | Optional target |
+| `rel` | `string` | Optional rel attribute |
+
+#### `BrandAction`
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `label` | `string` | CTA text |
+| `href` | `string` | Destination URL |
+| `ariaLabel` | `string` | Optional accessible label |
+| `target` | `_blank \| _self \| _parent \| _top` | Optional target |
+| `rel` | `string` | Optional rel |
+| `variant` | `"primary" \| "secondary" \| "ghost"` | Optional style hint (defaults to primary for the last CTA) |
+
+#### `BrandTheme`
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `primaryColor` | `string` | Accent color for links/buttons |
+| `backgroundColor` | `string` | Header/footer background |
+| `textColor` | `string` | Primary text color |
+| `fontFamily` | `string` | Font stack |
+| `linkColor` | `string` | Optional base link color |
+| `socialIconSize` | `string` | Size of the circular social buttons (defaults to `2.5rem`) |
+| `buttonTextColor` | `string` | Optional primary CTA text color override |
+| `ctaLayout` | `"inline" \| "stacked"` | Mobile CTA layout: side-by-side (`inline`) or one-per-row (`stacked`) |
+
+### Theming via CSS variables
+
+`styles/default.css` exposes CSS custom properties you can override globally:
+
+| Variable | Defaults to | Purpose |
+| --- | --- | --- |
+| `--brand-primary` | `#2563eb` | Accent + CTA background |
+| `--brand-bg` | `#0f172a` | Header/footer background |
+| `--brand-text` | `#f1f5f9` | Base text color |
+| `--brand-font` | `"Inter", system-ui` | Font stack |
+| `--brand-link` | `#94a3b8` | Link color |
+| `--brand-social-size` | `2.5rem` | Icon button size |
+| `--brand-button-text` | `#f8fafc` | Primary button text color |
+
+Set them once in your consuming app:
+
+```css
+:root {
+  --brand-primary: #ec4899;
+  --brand-font: "Space Grotesk", system-ui, sans-serif;
+  --brand-social-size: 2rem;
+}
+```
+
+### Storybook
+
+Run Storybook locally to explore examples and tweak controls:
+
+```bash
+bun run storybook
+```
+
+The stories showcase default, themed, and minimal configurations and expose controls for nav links, CTA buttons, and theme tokens.
+
+### Framework demo consumers
+
+Minimal demo apps for React (Vite), Next.js, TanStack Router (Vite), Vue, and Svelte are available under `examples/` and all share
+`examples/shared/brand-contract.json`.
+
+- `examples/react-vite`
+- `examples/next-app`
+- `examples/tanstack-vite`
+- `examples/vue-vite`
+- `examples/svelte-vite`
+
+Quick commands from repo root:
+
+```bash
+bun run demo:setup
+bun run demo:dev:react
+bun run demo:dev:vue
+bun run demo:dev:svelte
+bun run demo:build:all
+bun run test:smoke
+```
+
+See `examples/README.md` for details.
+
+### Dev Webapp Docs
+
+An interactive docs/playground app lives in `apps/docs` and is intentionally excluded from npm package publish size.
+
+```bash
+bun run docs:setup
+bun run docs:dev
+bun run docs:build
+```
+
+### Versioning and release
+
+This repo uses Changesets for controlled SemVer bumps.
+
+- every PR must include a changeset (minimum `patch`)
+
+```bash
+bun run changeset
+```
+
+Bump policy:
+
+- `patch`: bug fixes and non-breaking internal changes
+- `minor`: backward-compatible features (new optional fields/exports/adapters)
+- `major`: breaking API/schema/peer range changes
+
+Commit enforcement:
+
+- PR commits must follow Conventional Commits (checked by `.github/workflows/ci.yml`)
+- every PR must include a `.changeset/*.md` bump entry for `brand-shell` (`patch`/`minor`/`major`)
+- bump intent is auto-checked from commits:
+  - `feat` => at least `minor`
+  - `fix` / `perf` / `refactor` => at least `patch`
+  - `!` or `BREAKING CHANGE:` => `major`
+
+Release automation runs in `.github/workflows/release.yml`, which calls the same reusable verification workflow as CI before running Changesets publish steps:
+
+- if pending changesets exist, it opens/updates a release PR
+- once that release PR is merged, it publishes to npm with provenance

package/dist/brand-shell.schema.json

@@ -0,0 +1,89 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://brand-shell.dev/schema/brand-shell.schema.json",
+  "title": "Brand Shell Contract",
+  "description": "JSON Schema for Brand Shell details and theme payloads.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["details"],
+  "properties": {
+    "details": {
+      "$ref": "#/$defs/BrandDetails"
+    },
+    "theme": {
+      "$ref": "#/$defs/BrandTheme"
+    }
+  },
+  "$defs": {
+    "Target": {
+      "type": "string",
+      "enum": ["_blank", "_self", "_parent", "_top"]
+    },
+    "Variant": {
+      "type": "string",
+      "enum": ["primary", "secondary", "ghost"]
+    },
+    "BrandNavLink": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["label", "href"],
+      "properties": {
+        "label": { "type": "string", "minLength": 1 },
+        "href": { "type": "string", "minLength": 1 },
+        "ariaLabel": { "type": "string", "minLength": 1 },
+        "target": { "$ref": "#/$defs/Target" },
+        "rel": { "type": "string", "minLength": 1 }
+      }
+    },
+    "BrandAction": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["label", "href"],
+      "properties": {
+        "label": { "type": "string", "minLength": 1 },
+        "href": { "type": "string", "minLength": 1 },
+        "ariaLabel": { "type": "string", "minLength": 1 },
+        "target": { "$ref": "#/$defs/Target" },
+        "rel": { "type": "string", "minLength": 1 },
+        "variant": { "$ref": "#/$defs/Variant" }
+      }
+    },
+    "BrandDetails": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "homeHref": { "type": "string", "minLength": 1 },
+        "navLinks": {
+          "type": "array",
+          "default": [],
+          "items": { "$ref": "#/$defs/BrandNavLink" }
+        },
+        "primaryAction": { "$ref": "#/$defs/BrandAction" },
+        "secondaryAction": { "$ref": "#/$defs/BrandAction" },
+        "linkedin": { "type": "string", "minLength": 1 },
+        "gmail": { "type": "string", "minLength": 1 },
+        "github": { "type": "string", "minLength": 1 },
+        "twitter": { "type": "string", "minLength": 1 },
+        "discord": { "type": "string", "minLength": 1 },
+        "website": { "type": "string", "minLength": 1 },
+        "tagline": { "type": "string", "minLength": 1 }
+      }
+    },
+    "BrandTheme": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "primaryColor": { "type": "string", "minLength": 1 },
+        "backgroundColor": { "type": "string", "minLength": 1 },
+        "textColor": { "type": "string", "minLength": 1 },
+        "fontFamily": { "type": "string", "minLength": 1 },
+        "linkColor": { "type": "string", "minLength": 1 },
+        "socialIconSize": { "type": "string", "minLength": 1 },
+        "buttonTextColor": { "type": "string", "minLength": 1 },
+        "ctaLayout": { "type": "string", "enum": ["inline", "stacked"] }
+      }
+    }
+  }
+}