Merge pull request #1754 from gethinode/templatev2

Templatev2

Author: markdumay

.gitignore

@@ -1,6 +1,8 @@
 _vendor/
 prebuild/
 prebuild-headers/
+prebuild-headers-dev/
+prebuild-headers-prod/
 public/
 resources/
 node_modules/

CLAUDE.md

@@ -118,6 +118,48 @@ Components are mounted to multiple locations via `hugo.toml`:
 - `data/structures/` - Schemas
 - `assets/scss/modules/bookshop/` - Styles
 
+#### Bookshop Component Architecture
+
+Bookshop components follow a two-layer architecture:
+
+**1. Component partial** (e.g., `layouts/partials/assets/preview.html`):
+
+- Contains the core component logic and rendering
+- Uses **component-specific arguments** (e.g., `url`, `device`, `heading` for preview)
+- These arguments should be defined in the component's structure file
+
+**2. Bookshop wrapper** (e.g., `component-library/components/preview/preview.hugo.html`):
+
+- Calls the component partial with component-specific arguments
+- Wraps output with `utilities/section.html` for section-level styling
+- Passes **section arguments** to the wrapper (e.g., `id`, `background`, `width`, `justify`, `wrapper`, `fluid`, `theme`, `cover`, `overlay-mode`, `section-class`, `bg-class`)
+
+**Important distinctions:**
+
+- **Section arguments are NOT part of the component partial** - they're handled by the section wrapper
+- **Structure files should only include component-specific arguments** - arguments actively used by the partial
+- **Section arguments are defined in Bookshop specs** (`.hugo.html` and `.bookshop.yml`) but not in the component's structure file
+- Example: `preview.yml` defines `url`, `device`, `heading` (used by `preview.html`), but NOT `background`, `width`, etc. (only used by section wrapper)
+
+**Example structure:**
+
+```hugo
+{{/* preview.hugo.html - Bookshop wrapper */}}
+{{ $raw := partial "assets/preview.html" (dict
+    "url"      .url       {{/* component-specific */}}
+    "device"   .device    {{/* component-specific */}}
+    "heading"  .heading   {{/* component-specific */}}
+) }}
+
+{{ partial "utilities/section.html" (dict
+    "raw"            $raw
+    "background"     .background     {{/* section argument */}}
+    "width"          .width           {{/* section argument */}}
+    "theme"          .theme           {{/* section argument */}}
+    {{/* ... other section arguments ... */}}
+)}}
+```
+
 ### Version 2 Architecture Philosophy
 
 **Design Goal:** Hinode v2 is a minimal core theme that works standalone for documentation and blog sites. Optional features are provided through separate modules.
@@ -188,6 +230,164 @@ Extensive shortcode library in `layouts/_shortcodes/` provides Bootstrap compone
 - Content: image, video, table, timeline
 - Typography: abbr, kbd, mark, sub, sup
 
+### Argument and Type Initialization System
+
+Hinode uses `mod-utils` to provide a robust argument validation and initialization system
+for shortcodes, partials, and Bookshop components.
+
+**Key components:**
+
+- `utilities/InitArgs.html` - Validates and initializes arguments with type checking and
+  defaults
+- `utilities/InitTypes.html` - Loads type definitions and merges structure-specific with
+  global definitions
+- `data/structures/_arguments.yml` - Global argument definitions (type, default, options,
+  etc.)
+- `data/structures/<name>.yml` - Structure-specific argument definitions for each shortcode
+  or component
+
+**How it works:**
+
+1. **Structure definition inheritance:** Each shortcode/component has a structure file
+   (e.g., `example.yml`) that defines its arguments. These definitions automatically
+   inherit from the global `_arguments.yml` file.
+
+2. **Automatic camelCase conversion:** Hyphenated argument names (e.g., `show-preview`)
+   are automatically converted to camelCase (e.g., `showPreview`) for easier access in
+   templates. Both versions are available: `$args.show-preview` and `$args.showPreview`.
+
+3. **Default value application:** Arguments with `default` or `config` fields in their
+   definition are automatically initialized with those values if not provided by the user.
+
+4. **Type validation:** Arguments are validated against their declared types. The system
+   automatically casts between compatible types (e.g., string `"true"` to boolean `true`).
+
+5. **Deprecation warnings:** Deprecated arguments (marked with `deprecated` field) trigger
+   warnings when used, guiding users to the preferred alternative.
+
+**Structure definition format:**
+
+Structure files follow the DRY principle with clear separation of concerns:
+
+**Global definitions** (`mod-utils/data/structures/_arguments.yml`):
+
+- `type` - Argument data type
+- `default` - Default value (if applicable)
+- `options` - Valid values for select types
+- `comment` - Description of what the argument does
+
+**Component-specific definitions** (`data/structures/<name>.yml`):
+
+- `optional` - Whether argument is required or optional
+- `deprecated` - Version when argument was deprecated (component-specific)
+- `alternative` - Replacement argument when deprecated (component-specific)
+- `release` - Version when argument was introduced (component-specific)
+
+```yaml
+# Component structure file (e.g., data/structures/preview.yml)
+comment: >-
+  Renders a live URL preview with switchable device views.
+arguments:
+  url:
+    optional: false
+    release: v1.0.0
+  device:
+    optional: true
+    release: v1.0.0
+  heading:
+    optional: true
+    release: v1.0.0
+  old-param:
+    optional: true
+    deprecated: v1.1.0
+    alternative: device
+```
+
+```yaml
+# Global argument definitions (mod-utils/data/structures/_arguments.yml)
+arguments:
+  url:
+    type: string
+    comment: >-
+      Address of the link destination, either a local reference or an external
+      address. Include the `scheme` when referencing an external address.
+  device:
+    type: select
+    default: desktop
+    comment: >-
+      Device view to display by default in preview component. Determines the
+      initial iframe dimensions and active tab.
+    options:
+      values:
+        - desktop
+        - tablet
+        - mobile
+  heading:
+    type: heading
+    comment: >-
+      Heading of the content block, including a preheading and content element.
+```
+
+**When to add to _arguments.yml:**
+
+- New argument used by multiple components - add full type definition to global file
+- Component-specific argument - can define inline in structure file (but prefer global for reusability)
+- Override default or add options - define inline in structure file (inherits base type from global)
+
+**Common pitfall - Boolean argument handling:**
+
+When accessing boolean arguments that could be explicitly set to `false`, **DO NOT use the
+`or` operator** for fallback logic:
+
+```hugo
+{{/* WRONG - or operator treats false as falsy and skips it */}}
+{{- $showPreview := or $args.showPreview $args.show_preview }}
+
+{{/* CORRECT - directly access the camelCase version */}}
+{{- $showPreview := $args.showPreview }}
+```
+
+The `or` operator returns the first truthy value, so `or false <fallback>` will skip
+`false` and return the fallback instead of honoring the explicit `false` value.
+
+**Best practices:**
+
+- Always use `InitArgs` at the start of shortcodes and partials to validate arguments
+- Define structure files in `data/structures/` for all shortcodes and components
+- **Structure files should only reference arguments by name** - type definitions go in `_arguments.yml`
+- **Only include arguments actively used by the component partial** - section arguments (like `id`, `background`, `width`, `justify`, `wrapper`, `fluid`, `theme`, `cover`, `overlay-mode`, `section-class`, `bg-class`) are handled by the Bookshop section wrapper and should NOT be in the component's structure file
+- Add new argument types to `mod-utils/data/structures/_arguments.yml` for reuse across components
+- Mark `deprecated`, `alternative`, and `release` in **component structure files** (component-specific metadata)
+- Use hyphenated names for new arguments (e.g., `show-preview` not `show_preview`)
+- Access arguments via their camelCase versions (e.g., `$args.showPreview`)
+
+**Example usage in a shortcode:**
+
+```hugo
+{{/* Initialize and validate arguments */}}
+{{- $args := partial "utilities/InitArgs.html" (dict
+    "structure" "example"
+    "args" .Params
+    "named" .IsNamedParams
+    "group" "shortcode"
+) -}}
+
+{{/* Check for errors/warnings */}}
+{{- if or $args.err $args.warnmsg -}}
+    {{- partial (cond $args.err "utilities/LogErr.html" "utilities/LogWarn.html") (dict
+        "partial"  "shortcodes/example.html"
+        "msg"      "Invalid arguments"
+        "details"  ($args.errmsg | append $args.warnmsg)
+        "file"     page.File
+        "position" .Position
+    )}}
+{{- end -}}
+
+{{/* Access arguments using camelCase */}}
+{{- $showPreview := $args.showPreview }}
+{{- $showMarkup := $args.showMarkup }}
+```
+
 ### Content Security Policy
 
 CSP headers are auto-generated via Hugo's segments feature. The theme includes `mod-csp` for Content Security Policy management. Headers are defined in `netlify.toml` and generated via `npm run build:headers`.

assets/js/preview.js

@@ -0,0 +1,52 @@
+/**
+ * Preview Component - Auto-switch device on resize
+ * Automatically switches to next available device when current device panel is hidden
+ */
+
+function initPreviewAutoSwitch () {
+  const previewSections = document.querySelectorAll('section.preview')
+
+  previewSections.forEach(section => {
+    const buttons = section.querySelectorAll('.preview-controls .btn-group .btn')
+
+    if (buttons.length === 0) return
+
+    /**
+         * Check if active button is hidden and switch to next available
+         */
+    const checkAndSwitchDevice = () => {
+      // Find currently active button
+      const activeButton = Array.from(buttons).find(btn => btn.classList.contains('active'))
+
+      if (!activeButton) return
+
+      // Check if active button is hidden by CSS
+      const isHidden = window.getComputedStyle(activeButton).display === 'none'
+
+      if (isHidden) {
+        // Find all visible buttons
+        const visibleButtons = Array.from(buttons).filter(btn =>
+          window.getComputedStyle(btn).display !== 'none'
+        )
+
+        if (visibleButtons.length > 0) {
+          // Switch to first visible button (desktop -> tablet -> mobile priority)
+          visibleButtons[0].click()
+        }
+      }
+    }
+
+    // Debounced resize handler (avoid excessive checks)
+    let resizeTimer
+    window.addEventListener('resize', () => {
+      clearTimeout(resizeTimer)
+      resizeTimer = setTimeout(checkAndSwitchDevice, 150)
+    })
+
+    // Initial check on page load
+    checkAndSwitchDevice()
+  })
+}
+
+// Initialize on load (resize handler is set up inside initPreviewAutoSwitch)
+window.addEventListener('load', () => { initPreviewAutoSwitch() })

assets/scss/app-dart.scss

@@ -47,6 +47,7 @@
 @import "components/toast.scss";
 @import "components/timeline.scss";
 @import "components/toc.scss";
+@import "components/tooltip.scss";
 @import "components/video.scss";
 @import "common/animation.scss";
 @import "common/masonry.scss";

assets/scss/app.scss

@@ -45,6 +45,7 @@
 @import "components/toast.scss";
 @import "components/timeline.scss";
 @import "components/toc.scss";
+@import "components/tooltip.scss";
 @import "components/video.scss";
 @import "common/animation.scss";
 @import "common/masonry.scss";

assets/scss/components/_card.scss

@@ -75,6 +75,16 @@
     box-shadow: 0 10px 20px rgba(0, 0, 0, 0.12), 0 4px 8px rgba(0, 0, 0, 0.06);
 }
 
+.card-minimal {
+    border: none;
+    font-weight: bold;
+
+    &:hover,
+    &:focus {
+        text-decoration: underline;
+    }
+}
+
 // stylelint-disable annotation-no-unknown
 .card-body-link {
     color: $body-color if($enable-important-utilities, !important, null);

assets/scss/components/_docs.scss

@@ -3,11 +3,6 @@
     border-top-left-radius: #{$theme-border-radius};
     border-top-right-radius: #{$theme-border-radius};
     margin-left: #{$theme-border-radius};
-
-    &:hover,
-    &:focus {
-        border-bottom: 0;
-    }
 }
 
 .docs-panel,

assets/scss/components/_tooltip.scss

@@ -0,0 +1,8 @@
+.btn-tooltip a {
+    text-decoration: none;
+}
+
+.btn-tooltip a[href] {
+    color: var(--bs-link-color) !important;
+    text-decoration-color: var(--bs-link-color) !important;
+}

config/_default/menus/menus.en.toml

@@ -25,27 +25,3 @@
   pre = "fab medium"
   url = "https://medium.com/"
   weight = 30
-
-# toml-docs-start sample-navigation
-[[sample]]
-  name = "Blog"
-  pageRef = "/blog/"
-  weight = 10
-
-[[sample]]
-  name = "Projects"
-  pageRef = "/projects/"
-  weight = 20
-
-[[sample]]
-  name = "Sample project"
-  pageRef = "/projects/sample-project/"
-  parent = "Projects"
-  weight = 1
-
-[[sample]]
-  name = "Another project"
-  pageRef = "/projects/another-project/"
-  parent = "Projects"
-  weight = 2
-# toml-docs-end sample-navigation

config/_default/params.toml

@@ -286,7 +286,6 @@
 # provide default hero settings
 [modules.bookshop.hero]
   align = "start"
-#   backdrop = "/assets/img/nat-9l98kFByiao-unsplash.jpg"
   overlayMode = "dark"
   section = true
   default = ["section"]