@osimart/create-storefront 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,81 @@
-# Temporary Holding Version
+# @osimart/osimart-storefront
 
-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.
+The Osimart storefront **platform**, published as a private Nuxt layer. It has no look of
+its own. Every theme repo extends it:
+
+```ts
+// osimart-theme-base/nuxt.config.ts, store-offsiders/nuxt.config.ts, …
+export default defineNuxtConfig({ extends: ["@osimart/create-storefront"] });
+```
+
+| | Shopify | Osimart |
+|---|---|---|
+| Platform (hidden, updates everyone) | Shopify's servers | this package |
+| Theme (Dawn) | sections, snippets, layout, assets | `osimart-theme-base` repo |
+| Theme JSON | `templates/*.json`, `sections/*-group.json`, `config/settings_data.json` | `theme/` in the theme repo, `osimart-theme pull/push` |
+| A store's custom theme | copy of Dawn | a repo created from `osimart-theme-base` |
+
+## What's here
+
+```
+app/
+├── logic/                  the script of every theme file — the theme only imports it
+│   ├── sections/           HeroSection.js, MainProductSection.js, …   (#logic/sections/…)
+│   ├── components/         ProductCard.js, SiteHeader.js, …            (#logic/components/…)
+│   └── layouts/default.js
+├── composables/ services/ utils/ stores/ plugins/
+├── pages/                  routes: index, [category]/[product], categories/[slug], search,
+│                           pages/[handle] (each = "render this path's template");
+│                           checkout, login, user-profile, order-detail… (platform pages)
+├── components/             platform UI: SectionRenderer, builder/, checkout/,
+│                           common/ (OsiField, PhoneNumInput, DropdownSelect, Banner…)
+├── theme/                  registry.js (section map), controls.js, categoryTree.js
+└── app.vue
+bin/osimart-theme.mjs       CLI: themes / pull / push / publish
+nuxt/osi-sections.ts        builds the section map from the theme's app/sections
+THEME_DEV_API.md            the backend endpoints the CLI calls
+```
+
+A theme section looks like this — markup and CSS in the theme, logic from here:
+
+```vue
+<script setup>
+import useLogic from "#logic/sections/HeroSection";
+
+const props = defineProps({ section: Object, index: Number });
+const { asBanner } = useLogic({ props });
+</script>
+
+<template><MediaWithTextSection :section="asBanner" :index="index" /></template>
+```
+
+`useLogic` returns everything the original `<script setup>` declared, so the template can use
+any of it. Changing the logic changes every theme after its next build; the theme's markup
+and CSS are untouched.
+
+## Rules for code in this package
+
+- Never import with `~/` — inside a layer it means the theme. Use `#osi/…` (this `app/`),
+  `#logic/…`, or `#components` (which picks the theme's component when it has one).
+- `useLogic` return keys are the theme's API. Adding a key is a minor release; renaming or
+  removing one breaks themes, so it's a major.
+- A logic file with a top-level `await` wraps it in `withAsyncContext` (already done for
+  `AnnouncementBar.js`) so composables after it still have the component instance.
+
+## Releasing
+
+1. Bump `version` (semver): patch/minor for fixes and additions, **major** if a `useLogic`
+   key, a component's props or a route changes.
+2. `git tag v1.4.0 && git push --tags` → `release.yml` publishes to GitHub Packages and sends
+   `storefront-release` to every repo in `STORE_REPOS`; each one updates and redeploys.
+
+Repo setup once: secret `STORES_DISPATCH_TOKEN` (fine-grained PAT, contents read/write on the
+theme repos), variable `STORE_REPOS` (`ositcom/osimart-theme-base ositcom/store-offsiders`).
+Package settings: *Manage Actions access* → every theme repo; *Manage access* → each outside
+developer (read).
+
+## Working on the platform and a theme together
+
+```bash
+cd osimart-theme-base && npm link ../osimart-storefront && npm run dev
+```

package/THEME_DEV_API.md

@@ -0,0 +1,80 @@
+# Theme dev API (backend contract for `osimart-theme`)
+
+All under `theme-dev/` on the store's API host. The host picks the store, as for every
+storefront call.
+
+**Auth:** `Authorization: ThemeToken <token>`. The `ThemeAccessToken` belongs to one store
+(hashed, revocable, created in the dashboard). Anything else gets `401`.
+
+`<theme>` is either a theme id, `live` (the published theme) or `draft`.
+
+## Existing (from the theme access work)
+
+| Method | Path | Used by |
+|---|---|---|
+| GET | `theme-dev/schemas/` | `pull` → `.osimart/schemas.json` |
+| POST | `theme-dev/sections/sync/` | `push`: the theme's `*Section.schema.json` → `StoreSection` (`managed_by=CODE`) |
+
+`sections/sync/` body: `{ sections: [{ type, name, group?, allowed_templates, schema: { settings, blocks, max_blocks? } }], prune, dry_run }`.
+Response: `{ created, updated, unchanged, deleted, kept_in_use }` (lists of types).
+
+## New
+
+### `GET theme-dev/themes/`
+```json
+[{ "id": "uuid", "name": "Base", "role": "LIVE", "updated_at": "…" },
+ { "id": "uuid", "name": "Base (draft)", "role": "DRAFT", "updated_at": "…" }]
+```
+
+### `GET theme-dev/theme/?theme=<theme>`
+The theme's JSON exactly as stored, so a push of the same data is a no-op.
+```json
+{
+  "theme": { "id": "uuid", "name": "Base", "role": "LIVE", "version": "2026-10-12T13:40:11.120Z" },
+  "settings": { "PRIMARY_COLOR": "#20336b" },
+  "groups": {
+    "header": { "sections": [ { "key": "…", "type": "HEADER", "settings": {}, "blocks": [], "disabled": false } ] },
+    "footer": { "sections": [ … ] }
+  },
+  "templates": [
+    { "type": "INDEX", "suffix": "", "data": { "sections": [ … ] } },
+    { "type": "PRODUCT", "suffix": "alternate", "data": { "sections": [ … ] } },
+    { "type": "PAGE", "suffix": "contact", "data": { "sections": [ … ] } }
+  ]
+}
+```
+- `version` is any value that changes on every save of the theme, its templates or its groups
+  (`updated_at` of the newest row works).
+- `data` holds what the template stores (section order, settings, blocks); media stay as the
+  ids the dashboard saves, not resolved URLs.
+
+### `PUT theme-dev/theme/`
+```json
+{
+  "theme": "draft",
+  "base_version": "2026-10-12T13:40:11.120Z",
+  "dry_run": false,
+  "settings": { … },
+  "groups": { "header": { … }, "footer": { … } },
+  "templates": [ { "type": "PRODUCT", "suffix": "alternate", "data": { … } } ]
+}
+```
+- `theme: "draft"`: use the store's draft. If there is none, copy the live theme into a new
+  draft first (the same as a theme update, so the live theme stays as the rollback).
+- `base_version` not null and different from the theme's current `version` → `409`
+  (the merchant changed it in the dashboard after the pull). `null` = overwrite.
+- Any key left out (`settings`, `groups`, a template) is left as it is. Templates are
+  created or replaced by `(type, suffix)` and never deleted here.
+- Validate everything the dashboard validates (`get_section_schemas(store)`: section types,
+  setting ids, block types, `visible_if`) and answer `400` with field errors. On `dry_run`,
+  validate and report only.
+- Response:
+```json
+{ "theme": { "id": "uuid", "name": "…", "role": "DRAFT", "version": "…" },
+  "created": ["PRODUCT.alternate"], "updated": ["INDEX"], "unchanged": ["PRODUCT"],
+  "preview_url": "https://store.com/?preview_theme=<id>" }
+```
+
+### `POST theme-dev/themes/<id>/publish/`
+Makes that theme live (the previous live one becomes unpublished). Returns the theme
+(`{ id, name, role }`).

package/app/app.vue

@@ -0,0 +1,154 @@
+<script setup>
+// Global on purpose: every button and field in the storefront reads it.
+import "#osi/assets/css/osi-controls.css";
+import { parseIds } from "#osi/utils/analytics";
+
+const { load, dir, store, error } = useStorefront();
+const { tokens, rootClasses, fontLinks } = useThemeTokens();
+const { start: startBuilderPreview, stop: stopBuilderPreview } = useBuilderPreview();
+
+const { error: fetchError } = await useAsyncData("storefront", () => load());
+const shown = computed(() => error.value ?? fetchError.value ?? null);
+
+const isDev = import.meta.dev;
+
+onMounted(() => {
+  if (!import.meta.client) return;
+  let isFramed = false;
+  try {
+    isFramed = window.parent !== window || window.self !== window.top;
+  } catch {
+    isFramed = true;
+  }
+  const route = useRoute();
+  if (
+    isFramed ||
+    route?.path?.includes("__builder-preview") ||
+    route?.query?.osi_preview !== undefined ||
+    route?.query?.preview !== undefined
+  ) {
+    startBuilderPreview();
+  }
+});
+
+onBeforeUnmount(() => {
+  stopBuilderPreview();
+});
+
+// Favicon, title format, default description / share image, custom CSS.
+useThemeSeo();
+
+useHead({
+  htmlAttrs: computed(() => ({ dir: dir.value })),
+  noscript: computed(() =>
+    parseIds(store.value?.meta_pixel_id, "pixel").map((id) => ({
+      tagPosition: "bodyOpen",
+      innerHTML: `<img height="1" width="1" style="display:none" alt="" src="https://www.facebook.com/tr?id=${id}&ev=PageView&noscript=1" />`,
+    })),
+  ),
+  bodyAttrs: computed(() => ({
+    style: tokens.value,
+    class: rootClasses.value.filter((c) => /^osi-(btns|inputs|labels)/.test(c)),
+  })),
+    // A getter, not a snapshot: a font picked in the editor (or a theme that
+  // loads later) must add its stylesheet.
+  link: computed(() => [
+    ...fontLinks.value,
+    {
+      rel: "stylesheet",
+      href: "/css/output.css",
+    },
+  ]),
+})
+</script>
+
+<template>
+  <div v-if="shown" class="osi-fatal">
+    <p>This store isn't available right now.</p>
+
+   
+    <pre v-if="isDev" class="osi-fatal-detail">{{ shown.status ? `HTTP ${shown.status} — ` : "" }}{{ shown.message }}<template v-if="shown.data">
+{{ shown.data }}</template></pre>
+  </div>
+
+  <div v-else class="osi-root" :class="rootClasses" :style="tokens" :dir="dir">
+   <NuxtLoadingIndicator
+    color="var(--osi-primary-color)"
+    error-color="#dc2626"
+    :height="3"
+  />
+    <NuxtLayout>
+      <NuxtPage />
+    </NuxtLayout>
+    <div id="osi-teleport-root" />
+  </div>
+</template>
+
+<style>
+body {
+  font-family: var(--osi-font-body);
+  font-size: var(--osi-body-size);
+  color: var(--osi-text, #121212);
+  background: var(--osi-bg, #ffffff);
+}
+
+.osi-root {
+  font-family: var(--osi-font-body);
+  font-size: var(--osi-body-size);
+  color: var(--osi-text, #121212);
+  background: var(--osi-bg, #ffffff);
+}
+/* Section padding: useSectionShell writes desktop and phone values as
+   variables; these pick the one that applies. */
+.osi-section {
+  --osi-sec-pt-now: var(--osi-sec-pt);
+  --osi-sec-pb-now: var(--osi-sec-pb);
+  --osi-sec-pl-now: var(--osi-sec-pl);
+  --osi-sec-pr-now: var(--osi-sec-pr);
+}
+@media (max-width: 749px) {
+  .osi-section {
+    --osi-sec-pt-now: var(--osi-sec-pt-m, var(--osi-sec-pt));
+    --osi-sec-pb-now: var(--osi-sec-pb-m, var(--osi-sec-pb));
+    --osi-sec-pl-now: var(--osi-sec-pl-m, var(--osi-sec-pl));
+    --osi-sec-pr-now: var(--osi-sec-pr-m, var(--osi-sec-pr));
+  }
+}
+.osi-root h1,
+.osi-root h2,
+.osi-root h3,
+.osi-root h4,
+.osi-root h5,
+.osi-root h6 {
+  font-family: var(--osi-font-heading);
+}
+
+/* The old utility classes (login, account, checkout, cart… ) carry fixed
+   families from output.css; point them at the theme's fonts. `body` in front
+   beats the single-class utility and still reaches teleported drawers,
+   which sit outside .osi-root. */
+body .font-body,
+body .font-poppins,
+body .font-thoren {
+  font-family: var(--osi-font-body);
+}
+body .font-heading {
+  font-family: var(--osi-font-heading);
+}
+.osi-fatal {
+  padding: 4rem 1rem;
+  text-align: center;
+  font-family: system-ui, sans-serif;
+}
+.osi-fatal-detail {
+  display: inline-block;
+  margin-top: 1rem;
+  padding: 0.75rem 1rem;
+  text-align: start;
+  background: #fef2f2;
+  color: #991b1b;
+  border-radius: 6px;
+  font-size: 12px;
+  white-space: pre-wrap;
+}
+</style>