@giancarlosgza/blog-layer 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,74 @@
-# Temporary Holding Version
+# @giancarlosgza/blog-layer
 
-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.
+Nuxt 4 layer that adds a Firestore-backed blog to a site under a configurable base path: home feed,
+posts, tags, authors, series and paginated archive pages, cached read endpoints over the Firebase
+Admin SDK, RSS, a sitemap source and per-page SEO (meta, JSON-LD, generated OG images), styled
+with `@colorffy/ui` + `@colorffy/css`.
+
+It only adds the blog. The site keeps its own app shell (app.vue, layout, header, footer) and must
+load `@colorffy/css` itself. For a standalone blog site, install
+[`@giancarlosgza/blog-site-layer`](../blog-site-layer) instead, which wraps this layer in a full shell.
+
+The Firestore schema it reads is in [`docs/schema.md`](../../docs/schema.md); content is written by
+the blog admin.
+
+## Add a blog to a site
+
+```bash
+npm install @giancarlosgza/blog-layer
+```
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  extends: ['@giancarlosgza/blog-layer'],
+  blog: {
+    basePath: '/blog' // build time; '/' mounts the blog at the site root
+  },
+  css: ['@/assets/scss/main.scss', '@/assets/css/material-symbols.generated.css'],
+  site: { url: process.env.NUXT_SITE_URL, name: 'Acme' }
+})
+```
+
+```json
+// package.json
+"scripts": {
+  "prebuild": "blog-layer-subset-icons",
+  "predev": "blog-layer-subset-icons"
+}
+```
+
+Then point `GOOGLE_APPLICATION_CREDENTIALS` at the Firebase project's service account. The account
+alone selects the project.
+
+## What it mounts
+
+| Route | Name | Page |
+| :--- | :--- | :--- |
+| `<basePath>` | `blog` | Home feed (featured posts, tag filter, load more) |
+| `<basePath>/:slug` | `blog-post` | Post |
+| `<basePath>/page/:page` | `blog-archive` | Paginated archive (`/page/1` redirects home) |
+| `<basePath>/tags/:tag` | `blog-tag` | Posts with a tag |
+| `<basePath>/authors/:slug` | `blog-author` | Author and their posts |
+| `<basePath>/series/:slug` | `blog-series` | Series parts in reading order |
+| `<basePath>/rss.xml` | | RSS 2.0 feed |
+| `/api/blog/*` | | Cached Firestore reads (always at this path) |
+
+Link to the blog with route names (`{ name: 'blog' }`) or `useBlogPath().blogPath('/tags/css')`.
+Blog pages use the site's `default` layout; set `blog.layout` to use another one.
+
+## Options
+
+- **`blog.basePath`** (`nuxt.config`, default `/`): where the blog mounts.
+- **`blog.layout`** (`nuxt.config`, optional): layout for the blog pages.
+- **Brand:** override `blog.*` in the site's `app/app.config.ts`. Every key is documented in this
+  package's `app/app.config.ts`. `settings/general` in Firestore overrides the name and description.
+- **Widgets:** posts can embed `<div data-blog-widget="key" data-props='{...}'>`. A site registers
+  widgets by providing `blogWidgets` (`{ [key]: { descriptor, component } }`) from a plugin; without
+  one, placeholders render an "unavailable" fallback.
+- **Icons:** `blog-layer-subset-icons` scans the site, its `layers/*` and the installed blog layers
+  for Material Symbols in use and writes `public/icon-fonts/*` plus
+  `app/assets/css/material-symbols.generated.css` in the site.
+
+Inside the layer, files import each other through the `#blog/...` alias: `~` and `#shared` resolve
+to the site.

package/app/app.config.ts

@@ -0,0 +1,42 @@
+/**
+ * Blog identity defaults. The site overrides any of these in its own `app.config.ts`;
+ * `settings/general` (blog name, description) overrides the name and description at runtime.
+ * Arrays merge by concatenation across layers, so list defaults stay empty.
+ */
+export default defineAppConfig({
+  blog: {
+    /** Formal name: `og:site_name`, title template, structured data, RSS and OG image fallbacks. */
+    name: 'Blog',
+    /** Short name: navbar/footer fallback and SEO copy ("Articles by X on Blog."). */
+    shortName: 'Blog',
+    description: '',
+    /** Byline when a post has no author name. */
+    defaultAuthor: '',
+    home: {
+      /** Small line above the home heading (hidden when empty). */
+      eyebrow: '',
+      /** Highlighted word after the blog name in the home heading (hidden when empty). */
+      headingAccent: '',
+      title: 'Articles',
+      ogDescription: ''
+    },
+    archive: {
+      /** Meta description of `/page/N`, followed by " — page N." (defaults to "More articles from {shortName}"). */
+      description: ''
+    },
+    ogImage: {
+      /** Small line above the big word in the accent band (hidden when empty). */
+      kicker: '',
+      title: 'Blog',
+      accentColor: '#382bf0',
+      /** Wordmark at the top of the accent band, a path in the site's `public/` (hidden when empty). */
+      logo: ''
+    },
+    /** Publisher in the `Organization` JSON-LD (falls back to the blog name and URL). */
+    organization: {
+      name: '',
+      url: '',
+      sameAs: [] as string[]
+    }
+  }
+})

package/app/assets/scss/abstracts/_tokens.scss

@@ -0,0 +1,8 @@
+// Defaults; :where() lets the site's :root values win
+@layer abstracts.tokens {
+  :where(:root) {
+    --corner-radius-large: 18px;
+    --corner-radius-card: 20px;
+    --corner-radius-card-increased: 30px;
+  }
+}

package/app/assets/scss/abstracts/_type-scale.scss

@@ -0,0 +1,6 @@
+// Type scale
+$fs-landing-h1: clamp(2.5rem, calc(1.64rem + 3.57vw), 4.5rem);
+$fs-landing-card-md: clamp(1.375rem, calc(1.11rem + 1.12vw), 2rem);
+$fs-hub-title-long: clamp(2rem, calc(1.3rem + 2.2vw), 3rem);
+
+$ls-ledger-title: -2%;

package/app/assets/scss/abstracts/_variables.scss

@@ -0,0 +1 @@
+$easing-spring-elastic: linear(0, 0.002 0.3%, 0.007 0.6%, 0.029 1.3%, 0.065 2%, 0.119 2.8%, 0.237 4.2%, 0.659 8.7%, 0.778 10.2%, 0.871 11.6%, 0.95 13.1%, 1.009 14.6%, 1.033 15.4%, 1.052 16.2%, 1.066 17%, 1.078 17.9%, 1.085 18.8%, 1.088 19.7%, 1.088 20.7%, 1.085 21.7%, 1.074 23.6%, 1.032 28.7%, 1.014 31.4%, 1.006 33%, 1 34.6%, 0.993 38%, 0.992 41.9%, 0.999 51.4%, 1.001 57.6%, 1);

package/app/assets/scss/components/_icons.scss

@@ -0,0 +1,15 @@
+@layer base.icons {
+  .hover-rotate {
+    &:not(.disabled, :disabled) {
+      & i {
+        transition: rotate 2500ms var(--cffy-ease-spring);
+      }
+
+      &:is(:hover) {
+        & i {
+          rotate: 360deg;
+        }
+      }
+    }
+  }
+}

package/app/assets/scss/components/_symbols.scss

@@ -0,0 +1,20 @@
+// Material Symbols
+@layer base.symbols {
+  .material-symbols-rounded {
+    font-family: "Material Symbols Rounded";
+    font-weight: normal;
+    font-style: normal;
+    font-size: 24px;
+    line-height: 1;
+    letter-spacing: normal;
+    text-transform: none;
+    display: inline-block;
+    white-space: nowrap;
+    word-wrap: normal;
+    direction: ltr;
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+    text-rendering: optimizeLegibility;
+    font-feature-settings: "liga";
+  }
+}

package/app/assets/scss/main.scss

@@ -0,0 +1,9 @@
+// Abstracts
+@use './abstracts/tokens';
+
+// Components
+@use './components/icons';
+@use './components/symbols';
+
+// Pages
+@use './pages/core';

package/app/assets/scss/pages/_core.scss

@@ -0,0 +1,84 @@
+@use './core/layers';
+@use './core/shared-ui';
+@use './core/article-layout';
+@use './core/post-layout';
+@use './core/post-article-layout';
+@use './core/code-layout';
+@use './core/transitions-layout';
+@use './core/widgets';
+
+@layer overrides {
+  code,
+  .font-code {
+    font-family: var(--cffy-font-code), monospace;
+  }
+}
+
+@layer pages {
+  .section-hero {
+    & h1 {
+      & span {
+        --_hero-color-start-from: var(--cffy-secondary-base-fixed);
+        --_hero-color-start-to: var(--cffy-secondary-a30);
+        --_hero-color-end-from: var(--cffy-accent-base-fixed);
+        --_hero-color-end-to: var(--cffy-accent-a30);
+
+        --hero-color-start: var(--_hero-color-start-from);
+        --hero-color-end: var(--_hero-color-end-from);
+        --_space: in srgb;
+
+        background: linear-gradient(90deg var(--_space),
+            var(--hero-color-start),
+            var(--hero-color-end));
+        background-clip: text;
+        color: transparent;
+        -webkit-background-clip: text;
+        -webkit-text-fill-color: transparent;
+        animation: hero-color-change 3s linear infinite alternate;
+
+        @supports (background: linear-gradient(in oklch, #fff, #fff)) {
+          --_space: in oklch;
+        }
+
+        @media (prefers-reduced-motion: reduce) {
+          animation: none;
+        }
+      }
+    }
+  }
+
+  @property --hero-color-start {
+    syntax: '<color>';
+    inherits: false;
+    initial-value: #382bf0;
+  }
+
+  @property --hero-color-end {
+    syntax: '<color>';
+    inherits: false;
+    initial-value: #0075d6;
+  }
+
+  @keyframes hero-color-change {
+    to {
+      --hero-color-start: var(--_hero-color-start-to);
+      --hero-color-end: var(--_hero-color-end-to);
+    }
+  }
+
+  .gradient-blob {
+    --_color: var(--color, var(--cffy-secondary-base-fixed));
+
+    position: fixed;
+    top: 0;
+    right: 0;
+    width: 100vw;
+    aspect-ratio: 1 / 1;
+    border-radius: 50%;
+    pointer-events: none;
+    background: radial-gradient(circle at center, var(--_color) 0%, transparent 70%);
+    transform: translate(50%, -50%);
+    opacity: 0.45;
+    z-index: -1;
+  }
+}

package/app/assets/scss/pages/core/_article-layout.scss

@@ -0,0 +1,260 @@
+@use '@colorffy/css/scss/abstracts/mixins' as m;
+@use '../../abstracts/type-scale' as t;
+
+// Skips widget and Shiki subtrees
+$prose-scope: ':not(:where([data-blog-widget], .blog-code-host, .code-container) *)';
+
+@layer pages {
+  .blog-prose {
+    --_prose-space-xs: var(--cffy-space-8);
+    --_prose-space-sm: var(--cffy-space-24);
+    --_prose-space-md: var(--cffy-space-32);
+    --_prose-space-lg: var(--cffy-space-48);
+    --_prose-color: var(--cffy-muted-a10);
+    --_prose-heading-color: var(--cffy-on-background);
+    --_prose-border-color: var(--cffy-outline-surface);
+    --_prose-surface: var(--cffy-surface-container);
+    --_prose-anchor-offset: calc(var(--cffy-navbar-min-height, 4.25rem) + 1.5rem);
+
+    font-size: var(--cffy-fs-base);
+    line-height: 1.75;
+    color: var(--_prose-color);
+
+    @include m.media-query(768) {
+      font-size: .9375rem;
+    }
+
+    // Rhythm
+    & > * {
+      margin-block: 0;
+    }
+
+    & > * + * {
+      margin-block-start: var(--_prose-space-sm);
+    }
+
+    & > :is(h2, h3, h4, h5, h6) + * {
+      margin-block-start: var(--cffy-space-12);
+    }
+
+    & > h2 {
+      margin-block-start: var(--_prose-space-lg);
+    }
+
+    & > :is(h3, h4, h5, h6) {
+      margin-block-start: var(--_prose-space-md);
+    }
+
+    & > :is(figure, img, pre, table, hr, blockquote, .blog-code-host, [data-blog-widget]) {
+      margin-block: var(--_prose-space-md);
+    }
+
+    & > :first-child {
+      margin-block-start: 0;
+    }
+
+    & > :last-child {
+      margin-block-end: 0;
+    }
+
+    // Headings
+    & :is(h2, h3, h4, h5, h6)#{$prose-scope} {
+      font-family: var(--cffy-font-primary);
+      font-weight: var(--cffy-fw-600);
+      color: var(--_prose-heading-color);
+      letter-spacing: t.$ls-ledger-title;
+      text-wrap: balance;
+      scroll-margin-top: var(--_prose-anchor-offset);
+    }
+
+    & h2#{$prose-scope} {
+      font-size: t.$fs-landing-card-md;
+      line-height: 1.15;
+    }
+
+    & h3#{$prose-scope} {
+      font-size: var(--cffy-fs-xl);
+      line-height: 1.3;
+    }
+
+    & h4#{$prose-scope} {
+      font-size: var(--cffy-fs-lg);
+      line-height: 1.4;
+      letter-spacing: normal;
+    }
+
+    & :is(h5, h6)#{$prose-scope} {
+      font-size: var(--cffy-fs-base);
+      line-height: 1.5;
+      letter-spacing: normal;
+    }
+
+    // Text
+    & :is(p, li, dd, dt, td, th, figcaption, blockquote)#{$prose-scope} {
+      font-size: inherit;
+      line-height: inherit;
+      letter-spacing: normal;
+      overflow-wrap: break-word;
+    }
+
+    & p#{$prose-scope} {
+      color: var(--_prose-color);
+    }
+
+    & :is(strong, b)#{$prose-scope} {
+      font-weight: var(--cffy-fw-600);
+      color: var(--_prose-heading-color);
+    }
+
+    & :is(em, i:not(.material-symbols-rounded))#{$prose-scope} {
+      font-style: italic;
+    }
+
+    & a:not(.btn, .undecorated)#{$prose-scope} {
+      font-size: inherit;
+      font-weight: var(--cffy-fw-500);
+      line-height: inherit;
+      letter-spacing: inherit;
+
+      &:is(.text-link) {
+        border-bottom-color: var(--_link-underline-color);
+      }
+
+      &:is(:hover, :focus-visible):is(.text-link) {
+        border-bottom-color: currentColor;
+      }
+    }
+
+    // Lists
+    & :is(ul, ol)#{$prose-scope} {
+      margin-block-end: 0;
+      padding-inline-start: 1.5rem;
+    }
+
+    & li#{$prose-scope} {
+      padding-inline-start: .25rem;
+
+      & + li {
+        margin-block-start: var(--_prose-space-xs);
+      }
+
+      & > :is(ul, ol) {
+        margin-block-start: var(--_prose-space-xs);
+      }
+
+      & > p {
+        margin-block: 0;
+      }
+
+      &::marker {
+        color: var(--cffy-secondary-a10);
+      }
+    }
+
+    & ol#{$prose-scope} > li::marker {
+      font-family: var(--cffy-font-code);
+      font-weight: var(--cffy-fw-500);
+    }
+
+    & :is(ul, ol) ul#{$prose-scope} {
+      list-style-type: circle;
+    }
+
+    // Blockquote
+    & blockquote#{$prose-scope} {
+      padding-block: calc(var(--_prose-space-sm) / 2);
+      padding-inline: var(--_prose-space-sm);
+      background-color: color-mix(in srgb, var(--cffy-muted-base-fixed) 10%, transparent);
+      border-inline-start: var(--cffy-border-width-md) solid var(--cffy-muted-a10);
+      border-radius: 0 var(--cffy-radius-lg) var(--cffy-radius-lg) 0;
+
+      & > * {
+        margin-block: 0;
+      }
+
+      & > * + * {
+        margin-block-start: var(--_prose-space-xs);
+      }
+    }
+
+    // Inline code
+    & :not(pre) > code#{$prose-scope} {
+      padding: .125em .375em;
+      font-family: var(--cffy-font-code), monospace;
+      font-size: .875em;
+      color: var(--_prose-heading-color);
+      background-color: var(--_prose-surface);
+      border: var(--cffy-border-width-sm) solid var(--_prose-border-color);
+      border-radius: var(--cffy-radius-sm);
+      overflow-wrap: anywhere;
+      cursor: text;
+    }
+
+    // Raw blocks before Shiki hydrates
+    & > pre {
+      padding: .75rem 1rem;
+      font-family: var(--cffy-font-code), monospace;
+      font-size: .9em;
+      line-height: 1.6;
+      background-color: var(--_prose-surface);
+      border: var(--cffy-border-width-sm) solid var(--_prose-border-color);
+      border-radius: var(--cffy-radius-md);
+      overflow-x: auto;
+
+      & > code {
+        font-size: inherit;
+        color: inherit;
+        background: none;
+      }
+    }
+
+    & hr#{$prose-scope} {
+      height: 0;
+      border: 0;
+      border-block-start: var(--cffy-border-width-sm) solid var(--_prose-border-color);
+      opacity: 1;
+    }
+
+    // Tables
+    & table#{$prose-scope} {
+      display: block;
+      inline-size: fit-content;
+      max-inline-size: 100%;
+      overflow-x: auto;
+      border-collapse: collapse;
+      font-size: var(--cffy-fs-sm);
+
+      & :is(th, td) {
+        padding: .5rem .75rem;
+        text-align: start;
+        vertical-align: top;
+        border: var(--cffy-border-width-sm) solid var(--_prose-border-color);
+      }
+
+      & th {
+        font-weight: var(--cffy-fw-600);
+        color: var(--_prose-heading-color);
+        background-color: var(--_prose-surface);
+      }
+    }
+
+    // Media
+    & img#{$prose-scope} {
+      display: block;
+      inline-size: 100%;
+      block-size: auto;
+      border-radius: var(--corner-radius-large);
+    }
+
+    & figure#{$prose-scope} {
+      margin-inline: 0;
+    }
+
+    & figcaption#{$prose-scope} {
+      margin-block-start: var(--cffy-space-12);
+      font-size: var(--cffy-fs-xs);
+      color: var(--cffy-muted-a10);
+      text-align: center;
+    }
+  }
+}

package/app/assets/scss/pages/core/_code-layout.scss

@@ -0,0 +1,42 @@
+@layer pages {
+  .code-container {
+    --_code-container-border-color: var(--cffy-outline-surface);
+    --_code-container-bg-color: transparent;
+
+    position: relative;
+    background-color: var(--_code-container-bg-color);
+    border: var(--cffy-border-width-sm) solid var(--_code-container-border-color);
+    border-radius: var(--cffy-radius-md);
+    padding: 0;
+    margin: 0;
+    transition: background-color 200ms var(--cffy-ease-decelerate),
+      border 200ms var(--cffy-ease-decelerate);
+
+    &:is(:hover) {
+      --_code-container-border-color: var(--cffy-surface-a60);
+    }
+
+    & pre {
+      margin: 0;
+      padding: .75rem 1rem;
+      border-radius: var(--cffy-radius-md);
+      overflow-x: auto;
+    }
+
+    & code {
+      font-family: var(--cffy-font-code), monospace;
+      font-size: 0.9em;
+      line-height: 1.6;
+      background: transparent;
+    }
+
+    // Raw source until Shiki loads
+    & .code-loading-placeholder code {
+      white-space: pre;
+    }
+
+    &.code-copied {
+      --_code-container-border-color: var(--cffy-surface-a60);
+    }
+  }
+}

package/app/assets/scss/pages/core/_layers.scss

@@ -0,0 +1 @@
+@layer overrides, pages;