brand-shell 0.3.0 → 0.5.0

package/README.md

@@ -1,44 +1,40 @@
-## Brand Shell
+# 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.
+Reusable, validated header and footer UI with one shared contract across React, Next.js, TanStack Router, Vue, Svelte, and Web Components.
 
-### Installation
+## Install
 
 ```bash
 bun add brand-shell
 ```
 
-### Basic usage
+## Quick Start (React)
 
 ```tsx
-import { Header, Footer, type BrandDetails, type BrandTheme } from "brand-shell";
+import { Footer, Header, type BrandDetails, type BrandTheme } from "brand-shell";
 import "brand-shell/default.css";
 
 const details: BrandDetails = {
-  name: "Mounika Thota",
+  name: "Brand Shell",
   homeHref: "/",
   navLinks: [
-    { label: "Blog", href: "/blog" },
     { label: "Docs", href: "/docs" },
+    { label: "Blog", href: "/blog" },
   ],
-  primaryAction: { label: "Hire Me", href: "mailto:hello@example.com" },
-  secondaryAction: { label: "Resume", href: "/resume.pdf", target: "_blank" },
-  linkedin: "https://linkedin.com/in/example",
+  primaryAction: { label: "Contact", href: "mailto:hello@example.com" },
+  secondaryAction: { label: "GitHub", href: "https://github.com/example", target: "_blank" },
   github: "https://github.com/example",
-  twitter: "https://twitter.com/example",
-  gmail: "hello@example.com",
-  tagline: "Design-system quality shell for every project.",
+  linkedin: "https://linkedin.com/in/example",
+  tagline: "Build once. Reuse everywhere.",
 };
 
 const theme: BrandTheme = {
-  primaryColor: "#0ea5e9",
+  primaryColor: "#2563eb",
   backgroundColor: "#0f172a",
   textColor: "#f8fafc",
-  fontFamily: '"Inter", system-ui, sans-serif',
-  socialIconSize: "2.25rem",
 };
 
-export function Layout({ children }: { children: React.ReactNode }) {
+export function AppShell({ children }: { children: React.ReactNode }) {
   return (
     <>
       <Header details={details} theme={theme} />
@@ -49,268 +45,45 @@ export function Layout({ children }: { children: React.ReactNode }) {
 }
 ```
 
-### 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.
+## Framework Adapters
 
-```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"));
-}
+- React/Next/TanStack: `import { Header, Footer } from "brand-shell"`
+- Vue: `import { BrandHeader, BrandFooter } from "brand-shell/vue"`
+- Svelte: `import { brandShell } from "brand-shell/svelte"`
+- Web Components: `import { registerBrandShellElements, applyBrandShellProps } from "brand-shell/web"`
 
-const normalizedDetails = detailsCheck.normalized;
-const normalizedTheme = themeCheck.normalized;
-```
+All adapters use the same `BrandDetails` + `BrandTheme` contract.
 
-### JSON schema
+## Validation + Schema
 
-You can validate payloads in any runtime using the published schema:
+Use runtime validators and exported JSON Schema before rendering external payloads.
 
 ```ts
+import { validateBrandDetails, validateBrandTheme } from "brand-shell";
 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();
-```
+## Security Defaults
 
-```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>
-```
+- Unsafe link protocols are rejected during normalization.
+- `target="_blank"` links are hardened with `noopener noreferrer`.
+- Renderers use text/attributes only (no raw HTML rendering path).
 
-### 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
-```
+## Docs and Examples
 
-Bump policy:
+- Dev docs web app: `apps/docs`
+- Storybook: [Chromatic live preview](https://6992723e39539a58d711f188-ceiwmlxyrh.chromatic.com/)
+- Consumer demos: `examples/react-vite`, `examples/next-app`, `examples/tanstack-vite`, `examples/vue-vite`, `examples/svelte-vite`
 
-- `patch`: bug fixes and non-breaking internal changes
-- `minor`: backward-compatible features (new optional fields/exports/adapters)
-- `major`: breaking API/schema/peer range changes
+## Package Surface
 
-Commit enforcement:
+- Main: `brand-shell`
+- Adapters: `brand-shell/web`, `brand-shell/vue`, `brand-shell/svelte`
+- Schema: `brand-shell/schema` (or `brand-shell/schema.json`)
+- Styles: `brand-shell/default.css`
 
-- 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`
+## Versioning
 
-Release automation runs in `.github/workflows/release.yml`, which calls the same reusable verification workflow as CI before running Changesets publish steps:
+SemVer is managed with Changesets.
 
-- if pending changesets exist, it opens/updates a release PR
-- once that release PR is merged, it publishes to npm with provenance
+See [CONTRIBUTING.md](https://github.com/venwork-dev/brand-shell/blob/main/CONTRIBUTING.md) for development, commit policy, and release flow.

package/dist/default.css

@@ -40,7 +40,7 @@
   --_space: var(--brand-space-md);
 
   position: relative;
-  overflow: hidden;
+  overflow: visible;
   isolation: isolate;
   font-family: var(--_font);
   background:
@@ -349,8 +349,14 @@
     flex-wrap: nowrap;
     gap: 0.36rem;
     margin-top: 0.12rem;
-    padding-bottom: 0.12rem;
+    padding-block: 0.08rem 0.12rem;
     overflow-x: auto;
+    position: relative;
+    z-index: 1;
+  }
+
+  .brand-shell-header__social-link:hover {
+    transform: none;
   }
 }
 

package/package.json

@@ -1,7 +1,15 @@
 {
   "name": "brand-shell",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Reusable Header and Footer components with typed details and theme. Premium default UX, works in React, Vite, Next.js.",
+  "homepage": "https://github.com/venwork-dev/brand-shell#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/venwork-dev/brand-shell.git"
+  },
+  "bugs": {
+    "url": "https://github.com/venwork-dev/brand-shell/issues"
+  },
   "type": "module",
   "main": "./dist/index.mjs",
   "module": "./dist/index.mjs",