create-portfoliable 1.0.3

package/src/style.css

@@ -0,0 +1,88 @@
+/* File: create-portfoliable/src/style.css */
+/* Purpose: Define global runtime style resets and baseline viewport/body behavior. */
+/* Author: Lio Schimanko */
+
+/* MARK: NOTES */
+/* This stylesheet intentionally avoids local @import dependencies. */
+
+/* MARK: GLOBAL RESET */
+*, *::before, *::after {
+  box-sizing: border-box;
+}
+
+/* MARK: ROOT VIEWPORT SURFACE */
+body {
+  margin: 0;
+  background-color: var(--color-bg, var(--color-player-bg, #101218));
+  color: var(--color-black);
+  font-family: var(--font-family);
+  -webkit-font-smoothing: antialiased;
+  overflow: hidden;
+  height: 100vh;
+  width: 100vw;
+  transition: background-color 280ms ease;
+}
+
+html {
+  background-color: var(--color-bg, var(--color-player-bg, #101218));
+  transition: background-color 280ms ease;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  html,
+  body {
+    transition: none;
+  }
+}
+
+/* MARK: A11Y DARK THEME TOKENS */
+/* Mirrors Valence accessibility token roles so dark-mode toggles always affect the full app shell. */
+html.a11y-dark-mode {
+  --color-bg: var(--color-player-bg);
+  --color-surface: #1C1C1E;
+  --color-surface-border: rgba(255, 255, 255, 0.12);
+
+  --color-black: #FFFFFF;
+  --color-text-primary: #FFFFFF;
+  --color-text-secondary: #F5F5F5;
+  --color-text-muted: #B2B2B2;
+
+  --color-card-bg: var(--color-surface);
+  --color-card-border: var(--color-surface-border);
+  --color-kbd-border: rgba(255, 255, 255, 0.2);
+}
+
+/* MARK: A11Y HIGH CONTRAST TOKENS */
+/* Forces maximum contrast token values for users who opt into high-contrast mode. */
+html.a11y-high-contrast {
+  --color-bg: #000000;
+  --color-surface: #000000;
+  --color-surface-border: #FFFFFF;
+
+  --color-black: #FFFFFF;
+  --color-text-primary: #FFFFFF;
+  --color-text-secondary: #FFFFFF;
+  --color-text-muted: #FFFFFF;
+
+  --color-gray-dark: #FFFFFF;
+  --color-gray-med: #FFFFFF;
+  --color-gray-light: #FFFFFF;
+
+  --color-card-bg: #000000;
+  --color-card-border: #FFFFFF;
+  --color-kbd-border: #FFFFFF;
+}
+
+/* MARK: A11Y FORCED COLORS TOKENS */
+/* Maps runtime tokens to system color keywords when forced-colors is active. */
+html.a11y-forced-colors {
+  --color-bg: Canvas;
+  --color-surface: Canvas;
+  --color-text-primary: CanvasText;
+  --color-text-secondary: CanvasText;
+  --color-text-muted: GrayText;
+
+  --color-card-bg: Canvas;
+  --color-card-border: CanvasText;
+  --color-surface-border: CanvasText;
+}

package/templates/README.md

@@ -0,0 +1,242 @@
+# Portfoliable user manual
+
+This is the short end-user guide for a project created with:
+
+```bash
+npm create portfoliable@latest
+# or
+npm create portfoliable
+```
+
+Use it after scaffolding to run, edit, validate, and publish your portfolio.
+
+For a more detailed user-manual, please visit the official [Portfoliable documentation](https://www.portfoliable.js.org/docs/)
+
+## 1. Create and run a project
+
+```bash
+npm create portfoliable@latest my-portfolio
+# or
+npm create portfoliable my-portfolio
+cd my-portfolio
+npm run portfoliable
+```
+
+The app starts in local development mode and opens the browser by default.
+
+## 2. Main commands
+
+```bash
+npm run portfoliable
+npm run build
+npm run preview
+npm run validate:content
+npm run convert:audio
+npm run convert:video
+npm run portfoliable-create-case -- --name "My First Case"
+npm run add:language -- --code es --name Español --html-lang es-ES
+npm run portfoliable-thumbnail-options
+```
+
+## 3. Generated project structure
+
+A generated project usually includes:
+
+- `src/content/cases/` for case markdown files
+- `src/content/about/` for About content
+- `configs/` for runtime and locale configuration
+- `public/` for static assets and backend endpoints
+
+## 4. Create and edit a case
+
+```bash
+npm run portfoliable-create-case -- --name "My Case"
+```
+
+Each case should include:
+
+- a stable `id`
+- localized `title` and `shortDesc`
+- valid thumbnail metadata
+- readable localized markdown sections
+- correct share and link metadata when needed
+
+Example:
+
+```md
+<!-- lang:en -->
+## Project context
+This is the English case body.
+
+<!-- lang:pt -->
+## Contexto do projeto
+Este é o corpo do caso em português.
+```
+
+## 5. Add and remove languages
+
+To add a language, you can use the following command:
+
+```bash
+npm run add:language -- --code es --name Español --html-lang es-ES
+```
+
+To add locale-specific languages, you can use `--rtl` or `--ltf`, which will set the `dir` to left-to-right or right-to-left.
+
+```bash
+npm run add:language -- --code ar --name العربية --html-lang ar-SA --rtl
+npm run add:language -- --code it --name Italiano --html-lang it-IT --ltr
+```
+
+To remove a locale, use:
+
+```bash
+npm run delete:language -- --code es
+```
+
+You can also delete a default locale using:
+
+```bash
+npx portfoliable delete-language --code es --force 
+```
+
+Then fill in translated metadata and content blocks for the new locale.
+
+## 6. Thumbnail device catalog
+
+Inspect supported device combinations:
+
+```bash
+npm run portfoliable-thumbnail-options
+npm run portfoliable-thumbnail-options -- --full
+npm run portfoliable-thumbnail-options -- --json
+```
+
+Use the generated tuple in your case config, for example:
+
+```text
+thumbCategory=mobile thumbBrand=apple thumbModel=Apple iPhone 15 thumbColor=Black
+```
+
+## 7. Validate before shipping
+
+```bash
+npm run validate:content
+npm run build
+npm run preview
+```
+
+Validate early so missing metadata and broken locale sections are caught before production builds.
+
+## 8. Protected cases
+
+If a case needs a secure unlock flow, configure the backend endpoint in your app config and keep the real secret server-side.
+
+Do not store passwords directly in markdown files.
+
+### The setup flow
+
+1. Mark the case as protected in its frontmatter:
+
+```js
+{
+  id: 'mobile-product-launch',
+  isProtected: true
+}
+```
+
+2. Keep the unlock endpoint in the generated project config:
+
+```js
+export default {
+  protection: {
+    unlockEndpoint: '/api/unlock-case.php'
+  }
+};
+```
+
+3. Copy the example backend config into your project and add a hash for each protected case:
+
+```bash
+cp public/api/password.config.example.json public/api/password.config.json
+```
+
+Then add a record like:
+
+```json
+{
+  "cases": {
+    "mobile-product-launch": {
+      "hash": "$argon2id$v=19$m=65536,t=4,p=1$...generated-hash..."
+    }
+  }
+}
+```
+
+4. Generate a secure password hash:
+
+```bash
+npm run password:hash -- --case-id mobile-product-launch --password "your-secret"
+```
+
+5. Keep the real file private and protected by the server rules in `public/api/.htaccess`.
+
+### Important protections
+
+- `public/api/password.config.json` should stay out of git
+- the app should unlock the case only through the PHP endpoint
+- the unlock response should be treated as non-cacheable
+- frontend markdown is never the place to keep the real secret
+
+When a protected case loads, the app prompts for a passcode before revealing the locked content.
+
+## 9. Useful behavior to know
+
+- the home view renders case cards from metadata
+- cases support localized routes and localized metadata
+- the app supports visibility rules for web, crawler, and AI exposure
+- the reader can include summaries, audio, table of contents, and navigation controls
+
+## 10. Convert WAV files to MP3
+
+If you keep narration or voice assets as WAV while editing, you can convert them to MP3 before shipping:
+
+```bash
+npm run convert:audio
+```
+
+This command scans your project for `.wav` files and writes `.mp3` files in the same folders.
+
+Use this optional flag to target one directory:
+
+```bash
+npm run convert:audio -- --dir public/audio
+```
+
+`ffmpeg` is required (on macOS: `brew install ffmpeg`).
+
+## 11. Convert videos to MP4
+
+If you keep source footage in mixed formats while editing, you can convert videos to MP4 before shipping:
+
+```bash
+npm run convert:video
+```
+
+This command scans your project for video files (for example `.mov`, `.mkv`, `.avi`, `.webm`) and writes `.mp4` files in the same folders.
+
+Use this optional flag to target one directory:
+
+```bash
+npm run convert:video -- --dir public/video
+```
+
+Use `--force` to overwrite existing `.mp4` outputs:
+
+```bash
+npm run convert:video -- --dir public/video --force
+```
+
+`ffmpeg` is required (on macOS: `brew install ffmpeg`).
+
+This is the user-facing contract. For maintainer internals, use the repository root README instead.

package/templates/configs/i18n/i18n.config.js

@@ -0,0 +1,230 @@
+// File: templates/configs/i18n/i18n.config.js
+// Purpose: Provide runtime language configuration, translation resolution, and i18n helpers.
+// Author: Lio Schimanko
+
+// MARK: IMPORTS
+// Loads static translation labels and keyboard shortcut bindings used for runtime labels.
+import labelsByLocale from './i18n.labels.js';
+import { getShortcutDisplay, shortcutLabelBindings } from '../portfoliable.a11y.config.js';
+
+// MARK: LOCALE SOURCE OF TRUTH
+// Add/remove locales here. Keep keys quoted so Node scripts can parse this object reliably.
+export const LANGUAGE_CONFIG = Object.freeze({
+  "en": {
+    "name": "English",
+    "htmlLang": "en-US"
+  },
+  "he": {
+    "name": "עברית",
+    "htmlLang": "he-IL"
+  }
+});
+
+export const DEFAULT_LOCALE = 'en';
+export const SUPPORTED_LOCALES = Object.freeze(Object.keys(LANGUAGE_CONFIG));
+
+// Canonical list of RTL locale codes for direction detection.
+export const RTL_LOCALE_CODES = Object.freeze([
+  "arc",
+  "az-arab",
+  "azb",
+  "bal-arab",
+  "ckb",
+  "dv",
+  "fa",
+  "ff-adlm",
+  "glk",
+  "ha-arab",
+  "he",
+  "khw",
+  "ks-arab",
+  "ku-arab",
+  "lrc",
+  "mzn",
+  "nqo",
+  "pa-arab",
+  "pnb",
+  "ps",
+  "sd",
+  "syr",
+  "ug",
+  "ur",
+  "yi"
+]);
+
+// MARK: LOCALE NORMALIZATION
+// Normalizes arbitrary locale input into a lowercased canonical code.
+export function normalizeLocaleCode(value) {
+  return String(value || '').trim().toLowerCase();
+}
+
+// Resolves a locale to one of SUPPORTED_LOCALES or falls back to DEFAULT_LOCALE.
+export function resolveLocaleCode(value, fallback = DEFAULT_LOCALE) {
+  const normalized = normalizeLocaleCode(value);
+  if (SUPPORTED_LOCALES.includes(normalized)) {
+    return normalized;
+  }
+  return fallback;
+}
+
+// Returns true when a locale or its base language code is RTL.
+export function isRtlLocaleCode(value) {
+  const normalized = normalizeLocaleCode(value);
+  if (!normalized) return false;
+  if (RTL_LOCALE_CODES.includes(normalized)) return true;
+  const baseLocale = normalized.split('-')[0];
+  return RTL_LOCALE_CODES.includes(baseLocale);
+}
+
+// Resolves text direction for a locale with safe fallback behavior.
+export function resolveLocaleDirection(value, fallback = 'ltr') {
+  const normalized = normalizeLocaleCode(value);
+  if (isRtlLocaleCode(normalized)) {
+    return 'rtl';
+  }
+  if (SUPPORTED_LOCALES.includes(normalized)) {
+    return 'ltr';
+  }
+  return fallback === 'rtl' ? 'rtl' : 'ltr';
+}
+
+// MARK: LABEL RESOLUTION
+// Returns a human-readable language name from config, Intl, or locale code fallback.
+export function getLanguageDisplayName(localeCode) {
+  const normalized = resolveLocaleCode(localeCode, DEFAULT_LOCALE);
+  const configured = LANGUAGE_CONFIG[normalized]?.name;
+  if (typeof configured === 'string' && configured.trim().length > 0) {
+    return configured.trim();
+  }
+
+  try {
+    if (typeof Intl !== 'undefined' && typeof Intl.DisplayNames === 'function') {
+      const displayNames = new Intl.DisplayNames([normalized], { type: 'language' });
+      const resolved = displayNames.of(normalized);
+      if (resolved && resolved !== normalized) {
+        return resolved;
+      }
+    }
+  } catch {
+    // Uses locale code fallback below.
+  }
+
+  return normalized;
+}
+
+// MARK: ACTIVE LOCALE RESOLUTION
+// Resolves current locale from path segment, then query param, then default.
+function resolveActiveLanguage() {
+  const pathSegments = String(window.location.pathname || '')
+    .split('/')
+    .filter(Boolean)
+    .map((segment) => normalizeLocaleCode(segment));
+  const pathLocale = pathSegments[0] || '';
+  if (SUPPORTED_LOCALES.includes(pathLocale)) {
+    return pathLocale;
+  }
+
+  const urlParams = new URLSearchParams(window.location.search);
+  const urlLang = normalizeLocaleCode(urlParams.get('lang'));
+  if (SUPPORTED_LOCALES.includes(urlLang)) {
+    return urlLang;
+  }
+
+  return DEFAULT_LOCALE;
+}
+
+// MARK: SHORTCUT MARKUP HELPERS
+// Appends kbd markup to a base label when a shortcut is available.
+function appendShortcutLabel(baseLabel, shortcutValue, kbdClass = '') {
+  if (!baseLabel || !shortcutValue) return baseLabel;
+  const classMarkup = kbdClass ? ` class="${kbdClass}"` : '';
+  return `${baseLabel} <kbd${classMarkup}>${shortcutValue}</kbd>`;
+}
+
+// Keys that remain plain text without runtime kbd markup.
+const SKIP_SHORTCUT_MARKUP_KEYS = new Set([
+  'btn_return',
+  'a11y_size',
+  'a11y_dark',
+  'a11y_contrast',
+  'a11y_motion',
+  'a11y_tab',
+  'a11y_dyslexia'
+]);
+
+// MARK: TRANSLATION MAP BOOTSTRAP
+// Builds localized runtime labels by merging default-locale labels with per-locale overrides.
+function buildRuntimeTranslations() {
+  const baseTranslations = labelsByLocale && typeof labelsByLocale === 'object'
+    ? labelsByLocale
+    : {};
+  const runtime = {};
+
+  SUPPORTED_LOCALES.forEach((localeCode) => {
+    runtime[localeCode] = {
+      ...(baseTranslations[DEFAULT_LOCALE] || {}),
+      ...(baseTranslations[localeCode] || {})
+    };
+
+    // Always expose explicit localized language labels for contextual menu rendering.
+    runtime[localeCode][`lang_${localeCode}`] = getLanguageDisplayName(localeCode);
+  });
+
+  Object.entries(shortcutLabelBindings).forEach(([translationKey, binding]) => {
+    if (SKIP_SHORTCUT_MARKUP_KEYS.has(translationKey)) return;
+
+    const shortcutValue = getShortcutDisplay(binding.shortcutId);
+    if (!shortcutValue) return;
+
+    SUPPORTED_LOCALES.forEach((localeCode) => {
+      const baseLabel = runtime[localeCode]?.[translationKey];
+      runtime[localeCode][translationKey] = appendShortcutLabel(baseLabel, shortcutValue, binding.kbdClass || '');
+    });
+  });
+
+  return runtime;
+}
+
+// Builds the immutable runtime translation cache once at module load.
+const runtimeTranslations = buildRuntimeTranslations();
+
+// MARK: DOCUMENT LANGUAGE BOOTSTRAP
+// Initializes the active locale and applies lang/dir metadata to the document element.
+window.currentLang = resolveActiveLanguage();
+const htmlLangTag = LANGUAGE_CONFIG[window.currentLang]?.htmlLang || window.currentLang;
+document.documentElement.lang = htmlLangTag;
+document.documentElement.dir = resolveLocaleDirection(window.currentLang, 'ltr');
+
+// MARK: PUBLIC TRANSLATION API
+// Exposes runtime translation maps and keys requiring plain text insertion.
+export const translations = runtimeTranslations;
+const PLAIN_TEXT_I18N_KEYS = new Set(['h1_title']);
+
+// Returns translated value for the active locale with fallback to default locale and key.
+export function t(key) {
+  const activeLocale = resolveLocaleCode(window.currentLang, DEFAULT_LOCALE);
+  return translations[activeLocale]?.[key] || translations[DEFAULT_LOCALE]?.[key] || key;
+}
+
+// MARK: DOM TRANSLATION APPLIER
+// Applies translations to data-i18n nodes.
+export function applyTranslations() {
+  // Applies runtime labels to any document node annotated with data-i18n.
+  document.querySelectorAll('[data-i18n]').forEach((el) => {
+    const key = el.getAttribute('data-i18n');
+    if (!key) return;
+
+    const activeLocale = resolveLocaleCode(window.currentLang, DEFAULT_LOCALE);
+    if (translations[activeLocale] && translations[activeLocale][key]) {
+      const localizedValue = translations[activeLocale][key];
+      if (PLAIN_TEXT_I18N_KEYS.has(key)) {
+        el.textContent = localizedValue;
+      } else {
+        el.innerHTML = localizedValue;
+      }
+    }
+  });
+}
+
+// Runs one translation pass once the initial document is ready.
+document.addEventListener('DOMContentLoaded', applyTranslations);