@osimart/create-storefront 1.0.25 → 1.0.27

package/README.md

@@ -1,42 +1,99 @@
-# @osimart/create-storefront
+# Osimart Storefront
 
-The Osimart storefront **platform**, published as a private Nuxt layer. It has no look of
-its own. Every theme repo extends it:
+`@Osimart/create-storefront` is the shared storefront platform for Osimart themes. It provides the Nuxt foundation, store-facing pages, commerce behavior, reusable UI, theme integration, and the `Osimart-theme` developer CLI. A theme extends this package and supplies its own presentation: page layouts, section markup, component styling, assets, and theme configuration.
+
+This package is intended to be consumed by an Osimart theme project. It is not a standalone store template. The theme project is where you build the customer-facing look; this package supplies the shared platform that powers it.
+
+## How the pieces fit together
+
+| Part | Owns |
+| --- | --- |
+| `@Osimart/create-storefront` (this package) | Nuxt configuration, routes, shared commerce and account behavior, platform components, theme utilities, and the theme CLI |
+| Osimart theme project | Layouts, section and component markup, CSS, images and fonts, section schemas, and theme JSON settings |
+| Osimart store service | Store data and API operations used by the storefront and theme tools |
+
+The platform exposes logic for theme files through `#logic`. A theme can use that logic while keeping control of its Vue template and styles. This lets shared behavior improve across themes without forcing every theme to use the same design.
+
+## Requirements
+
+- Node.js and npm versions supported by your Nuxt project.
+- An Osimart theme repository or a new theme project based on the Osimart theme structure.
+- Access to the `@osimart/create-storefront` package registry if the package is private in your environment.
+- An Osimart store API URL and a theme access token for commands that read or write a store's theme.
+
+## Add the platform to a theme project
+
+Install the package in the theme project:
+
+```bash
+npm install @osimart/create-storefront
+```
+
+If registry authentication is required, configure npm using the credentials provided for your Osimart development environment. Do not commit access tokens to the repository.
+
+Extend the platform from the theme's `nuxt.config.ts`:
 
 ```ts
-// osimart-theme-base/nuxt.config.ts, store-offsiders/nuxt.config.ts, …
-export default defineNuxtConfig({ extends: ["@osimart/create-storefront"] });
+export default defineNuxtConfig({
+  extends: ["@osimart/create-storefront"],
+});
+```
+
+The layer configures the `#osi` alias for platform app code, the `#logic` alias for shared theme logic, global platform components, and the section registry module. The theme can add its own components and section files in the usual Nuxt locations.
+
+Install the theme project's remaining dependencies and start it using its scripts. For example, the Osimart base theme uses:
+
+```bash
+npm install
+npm run dev
 ```
 
-| | 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` |
+The base theme's `dev` script runs `Osimart-theme dev`, which starts Nuxt in a theme development session. Use `npm run dev:live` when you specifically need to run plain `nuxt dev` without the theme preview session.
 
-## What's here
+## Configure the store connection
 
+Set environment variables in the theme project's local `.env` file. The exact API host depends on your Osimart environment:
+
+```dotenv
+NUXT_PUBLIC_STORE_API_BASE=https://your-store-api.example/
+Osimart_THEME_TOKEN=your-theme-access-token
 ```
+
+`NUXT_PUBLIC_STORE_API_BASE` is the API base used by the storefront. The theme CLI also uses it to reach the theme development API. `Osimart_THEME_TOKEN` authorizes theme CLI operations. Keep the token private and out of source control.
+
+In production, the storefront API is same-origin by default; the Nuxt runtime config's `storeApiBase` defaults to an empty string. Configure the deployment and API routing for your Osimart environment accordingly. The public runtime setting can be overridden with `NUXT_PUBLIC_STORE_API_BASE` when needed.
+
+## Project structure
+
+The main platform areas are:
+
+```text
 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
+├── logic/
+│   ├── sections/       Shared behavior used by theme section components
+│   ├── components/     Shared behavior used by theme components
+│   └── layouts/        Shared layout behavior
+├── pages/              Platform routes such as checkout, login, and account pages
+├── components/
+│   ├── checkout/       Checkout UI
+│   ├── common/         Shared controls and UI primitives
+│   └── builder/        Theme builder and preview UI
+├── composables/        Reusable Vue/Nuxt behavior
+├── services/           API and domain service code
+├── stores/             Pinia stores
+└── theme/              Theme registries and control helpers
+bin/Osimart-theme.mjs   Theme development and synchronization CLI
+nuxt/                   Nuxt modules for section registration and dev preview
+THEME_DEV_API.md        Theme CLI API contract
 ```
 
-A theme section looks like this — markup and CSS in the theme, logic from here:
+The consuming theme typically contains its own `app/sections`, `app/components`, `app/layouts`, styles, public assets, and a `theme/` directory with its settings, section groups, and page templates.
+
+## Customize a theme
+
+### Change a section's markup or styling
+
+Theme section files own their template and CSS. Import the matching platform logic when the section needs shared data or behavior:
 
 ```vue
 <script setup>
@@ -46,36 +103,111 @@ const props = defineProps({ section: Object, index: Number });
 const { asBanner } = useLogic({ props });
 </script>
 
-<template><MediaWithTextSection :section="asBanner" :index="index" /></template>
+<template>
+  <MediaWithTextSection :section="asBanner" :index="index" />
+</template>
+
+<style scoped>
+/* Theme-specific presentation */
+</style>
+```
+
+Keep the props and emitted events expected by the shared component logic. The logic's returned values are part of the theme integration API: adding a returned value is generally compatible, while renaming or removing one can break consuming themes.
+
+### Override a platform component
+
+Create a theme component with the same component name and Nuxt will resolve the theme implementation for that theme. Use the shared component logic where appropriate, then own the template and style in the theme. This is useful when a theme needs a different design while preserving established cart, product, or navigation behavior.
+
+### Add a section type
+
+Create a Vue section and its schema in the theme project. For example:
+
+`app/sections/LookbookSection.vue`
+
+```vue
+<script setup>
+const props = defineProps({ section: Object, index: Number });
+</script>
+
+<template>
+  <section class="lookbook">
+    <h2>{{ section.settings?.HEADING }}</h2>
+  </section>
+</template>
+```
+
+`app/sections/LookbookSection.schema.json`
+
+```json
+{
+  "name": "Lookbook",
+  "templates": ["INDEX", "PAGE"],
+  "settings": [
+    { "id": "HEADING", "type": "text", "label": "Heading" }
+  ],
+  "blocks": []
+}
 ```
 
-`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.
+The section registry discovers theme section files. The schema describes the settings and blocks available to the Osimart theme editor. Push the theme to synchronize the schema with the store, then add the section to the relevant theme template or group.
+
+### Customize theme settings and page composition
+
+Theme JSON is stored in the theme project's `theme/` directory:
+
+```text
+theme/
+├── config/settings_data.json
+├── sections/header-group.json
+├── sections/footer-group.json
+└── templates/
+    ├── index.json
+    ├── product.json
+    └── page.contact.json
+```
+
+Use the theme CLI to pull the current store theme, edit its JSON locally, and push changes to a draft. This supports working in version control while keeping the dashboard theme editor as another way to manage the same theme data.
+
+## Theme development CLI
 
-## Rules for code in this package
+The package exposes the `Osimart-theme` executable. The Osimart base theme provides npm scripts for common commands:
 
-- 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.
+| Command | Purpose |
+| --- | --- |
+| `npm run dev` | Start a Nuxt theme development session against a store draft; saves in `theme/` are synchronized during the session. |
+| `npm run theme:list` | List themes available to the configured store. |
+| `npm run theme:pull` | Pull the live theme into local `theme/` files. |
+| `npm run theme:pull -- --theme <id>` | Pull a specific theme by ID. |
+| `npm run theme:push` | Push local theme files to a draft theme. |
+| `npm run theme:push -- --theme live` | Push directly to the live theme. Use with care. |
+| `npx Osimart-theme publish <id>` | Make the specified theme live. |
 
-## Releasing
+The CLI also supports `--dry-run`, `--force`, and `--prune` on push, and `--delete` on pull. Run `npx Osimart-theme` to print its usage. A normal push checks whether the remote theme changed since the last pull; pull and reconcile those edits before pushing, or use `--force` when intentionally replacing the remote version.
 
-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.
+## Customizing platform behavior
 
-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).
+If you are developing this package itself, shared behavior lives under `app/logic`, reusable platform UI under `app/components`, and shared Nuxt/Vue behavior under `app/composables`, `app/services`, and `app/stores`. Prefer changing shared logic here when the behavior should apply to all Osimart themes. Prefer changing a theme's Vue/CSS when the change is visual or unique to one storefront.
 
-## Working on the platform and a theme together
+Inside this Nuxt layer, avoid `~/` imports because `~` resolves to the consuming theme. Use:
+
+- `#osi/...` for this package's app files, such as composables and services.
+- `#logic/...` for shared section and component logic.
+- `#components` when using components that a theme may override.
+
+Treat component props, emitted events, routes, and the objects returned by `useLogic` as public integration points. Update theme consumers when changing those contracts.
+
+## Package development and releases
+
+To work on a theme and a local copy of this package together, link the package into the theme project, then run the theme's development command. For example, from the theme project:
 
 ```bash
-cd osimart-theme-base && npm link ../create-storefront && npm run dev
+npm link ../osimart-storefront
+npm run dev
 ```
+
+Package releases use semantic versioning. Compatible fixes and additions should preserve existing theme APIs; breaking changes to public component props, routes, or logic return values should be treated as major changes. Theme projects can update the dependency with their package manager and then rebuild/redeploy through their normal Osimart deployment process.
+
+## More information
+
+- [Osimart theme development API](./THEME_DEV_API.md) — endpoints and payloads used by the theme CLI.
+- The Osimart base theme README — theme project setup, theme file structure, deployment, and theme-specific customization examples.

package/app/components/checkout/CheckoutView.vue

@@ -272,6 +272,7 @@
                 <PhoneNumInput
                   v-model="formData.mobile_number"
                   variant="bare"
+                  :themed-popup="true"
                   :error="phoneHasError"
                   @update="onPhoneUpdate"
                 />
@@ -375,6 +376,7 @@
                   @update:model-value="selectCountry($event); clearFieldError('country')"
                   placeholder="Country"
                   searchable
+                  themed
                   local-search
                   full-width
                   field="country"
@@ -408,6 +410,7 @@
                   @update:model-value="selectZone($event); clearFieldError('zone')"
                   placeholder="Zone"
                   searchable
+                  themed
                   local-search
                   full-width
                   field="zone"

package/app/components/common/DropdownSelect.vue

@@ -97,16 +97,20 @@
      <div
   v-if="open && !disabled"
   ref="menuRef"
-  :style="[floatingStyles, menuWidthStyle, { zIndex: dropdownZIndex }]"
-  class="absolute font-poppins bg-white border border-gray-300 rounded-md shadow-lg max-h-60 overflow-auto dropdown-select-popup"
-  :class="dropdownWidth ? '' : 'w-max max-w-xs'"
+  :style="[floatingStyles, menuWidthStyle, themeVars, { zIndex: dropdownZIndex }]"
+  class="absolute font-poppins border rounded-md shadow-lg max-h-60 overflow-auto dropdown-select-popup"
+  :class="[
+    dropdownWidth ? '' : 'w-max max-w-xs',
+    themed ? 'dropdown-select-popup--themed' : 'bg-white border-gray-300',
+  ]"
   @scroll.passive="onScroll"
 >
         <!-- Search -->
         <div v-if="searchable" class="p-2">
           <input
             v-model="searchQuery"
-            class="bg-input w-full border px-2 py-1 rounded text-sm focus:outline-none"
+            class="w-full border px-2 py-1 rounded text-sm focus:outline-none"
+            :class="themed ? 'dd-search' : 'bg-input'"
             placeholder="Search..."
           />
         </div>
@@ -116,7 +120,8 @@
             v-for="opt in filteredOptions"
             :key="opt.value"
             :style="{ color: opt.color }"
-            class="px-4 py-2 flex justify-between items-center hover:bg-gray-100 cursor-pointer"
+            class="px-4 py-2 flex justify-between items-center cursor-pointer"
+            :class="themed ? 'dd-option' : 'hover:bg-gray-100'"
             @click="toggleOption(opt.value)"
           >
             <div class="flex items-center gap-2 min-w-0">
@@ -141,7 +146,7 @@
           </li>
         </ul>
 
-        <div v-else-if="!loading" class="px-4 py-2 text-fifthosiblue text-center text-sm">
+        <div v-else-if="!loading" class="px-4 py-2 text-fifthosiblue text-center text-sm" :class="{ 'dd-empty': themed }">
           No results
         </div>
 
@@ -193,6 +198,11 @@ const props = defineProps({
   // Explicit width for the dropdown menu (any valid CSS width, e.g. '320px',
   // '24rem', '100%'). Overrides the default w-max/max-w-xs/minWidth-match behavior.
   dropdownWidth: { type: String, default: null },
+  // Opt-in: the popup takes its colours from the storefront theme variables
+  // (the same ones the form fields use) instead of the hardcoded white/gray.
+  // The menu is teleported to <body>, so the variables are copied from the
+  // trigger's element when it opens. Off = every existing usage is unchanged.
+  themed: { type: Boolean, default: false },
 });
 const parentModalZIndex = inject("modalZIndex", null);
 const dropdownZIndex = computed(() =>
@@ -211,6 +221,38 @@ const rootRef = ref(null);
 const triggerBtnRef = ref(null);
 const triggerWidth = ref(0);
 
+// CSS variables the themed popup needs. The teleported menu sits outside the
+// element that defines them, so they're read from the trigger when it opens.
+// Names match osi-controls.css: the Inputs theme group (--osi-input-*) and the
+// colour scheme (--osi-bg / --osi-text / --osi-border).
+const THEME_VARS = [
+  "--osi-bg",
+  "--osi-text",
+  "--osi-border",
+  "--osi-input-bg",
+  "--osi-input-fg",
+  "--osi-input-border-color",
+  // The checkout's card colours (set inline on .osi-ck, so only present there).
+  "--ck-card-bg",
+  "--ck-card-text",
+  "--ck-card-border",
+];
+const themeVars = ref({});
+
+function readThemeVars() {
+  if (!props.themed || !rootRef.value) {
+    themeVars.value = {};
+    return;
+  }
+  const cs = getComputedStyle(rootRef.value);
+  const vars = {};
+  for (const name of THEME_VARS) {
+    const value = cs.getPropertyValue(name).trim();
+    if (value) vars[name] = value;
+  }
+  themeVars.value = vars;
+}
+
 const menuWidthStyle = computed(() => {
   if (props.dropdownWidth) return { width: props.dropdownWidth };
   if (!props.autoWidth) return { minWidth: triggerWidth.value + 'px' };
@@ -410,6 +452,7 @@ watch(open, (isOpen) => {
   if (isOpen) {
     eventBus.emit("dropdown:opened", instanceId);
     triggerWidth.value = rootRef.value ? rootRef.value.offsetWidth : 0;
+    readThemeVars();
     document.addEventListener("mousedown", handleDocumentClick, true);
     emit("open");
   } else {
@@ -429,4 +472,30 @@ onBeforeUnmount(() => {
 onUnmounted(() => {
   eventBus.off("dropdown:opened", onGlobalDropdownOpened);
 });
-</script>
+</script>
+
+<style scoped>
+/* Only applied when the `themed` prop is set. Every colour falls back to the
+   old hardcoded one, so a themed popup outside the storefront still looks
+   the same as before. */
+.dropdown-select-popup--themed {
+  background: var(--osi-input-bg, var(--ck-card-bg, var(--osi-bg, #fff)));
+  color: var(--osi-input-fg, var(--ck-card-text, var(--osi-text, inherit)));
+  border-color: var(--osi-input-border-color, var(--ck-card-border, var(--osi-border, #d1d5db)));
+}
+.dropdown-select-popup--themed .dd-option:hover {
+  background: color-mix(in srgb, currentColor 8%, transparent);
+}
+.dropdown-select-popup--themed .dd-search {
+  background: transparent;
+  color: inherit;
+  border-color: color-mix(in srgb, currentColor 20%, transparent);
+}
+.dropdown-select-popup--themed .dd-search::placeholder {
+  color: color-mix(in srgb, currentColor 50%, transparent);
+}
+.dropdown-select-popup--themed .dd-empty {
+  color: inherit;
+  opacity: 0.6;
+}
+</style>

package/app/components/common/PhoneNumInput.vue

@@ -14,6 +14,7 @@
       :searchable="true"
       :local-search="true"
       smallText
+      themed
       @search="onSearch"
       @update:modelValue="onCountryChange"
       @open="isFocused = true"
@@ -64,7 +65,8 @@
     v-else
     class="w-full"
     :class="[
-      effectiveVariant === 'underline' ? 'font-thoren relative' : 'font-poppins'
+      effectiveVariant === 'underline' ? 'font-thoren relative' : 'font-poppins',
+      { 'phone-input-themed': themedPopup && effectiveVariant === 'bare' }
     ]"
   >
     <label
@@ -100,6 +102,7 @@
           @update:modelValue="onCountryChange"
           @open="isFocused = true"
           @close="isFocused = false"
+          :themed="themedPopup"
           :fullWidth="false"
           class="shrink min-w-[90px]"
           :class="ispopup ? 'lg:min-w-[70px]':'lg:min-w-[140px]'"
@@ -196,6 +199,9 @@ const props = defineProps({
   inputClass: { type: [String, Array, Object], default: 'osi-input' },
   inputId: { type: String, default: '' },
   disabled: { type: Boolean, default: false },
+  // Non-theme variants only: opt the country popup into the theme colours.
+  // (The `theme` variant is always themed.)
+  themedPopup: { type: Boolean, default: false },
 })
 
 const emit = defineEmits(['update:modelValue', 'update', 'clear-error'])
@@ -431,4 +437,20 @@ const getFlagUrl = (code) => {
   outline: none !important;
   box-shadow: none !important;
 }
-</style>
+
+/* Keep the compact bare layout while using the shared Inputs color tokens. */
+.phone-input-themed .dropdown-trigger-btn,
+.phone-input-themed .text-input {
+  color: var(--osi-input-fg, inherit);
+}
+.phone-input-themed .text-input {
+  background-color: var(--osi-input-bg, transparent);
+}
+.phone-input-themed .text-input::placeholder {
+  color: var(--osi-input-placeholder, currentColor);
+  opacity: 1;
+}
+.phone-input-themed .border-r {
+  border-color: var(--osi-input-border-color, #e5e7eb);
+}
+</style>

package/app/logic/components/SiteHeader.js

@@ -146,6 +146,8 @@ export default function useLogic() {
     if (s.HEADER_ICON_BORDER) style["--osi-header-icon-border"] = s.HEADER_ICON_BORDER;
     if (s.HEADER_CART_BADGE_BG) style["--osi-header-badge-bg"] = s.HEADER_CART_BADGE_BG;
     if (s.HEADER_CART_BADGE_TEXT) style["--osi-header-badge-text"] = s.HEADER_CART_BADGE_TEXT;
+    if (s.HEADER_BORDER_COLOR) style["--osi-header-border"] = s.HEADER_BORDER_COLOR;
+    if (s.HEADER_BORDER_WIDTH) style["--osi-header-border-w"] = `${s.HEADER_BORDER_WIDTH}px`;
     style["--osi-header-pad-y"] = `${s.HEADER_PADDING_Y}px`;
     // Side padding lives on the header itself, not on the inner box — see the
     // note on .osi-header-inner below. 16 is COMMON_STYLE_SETTINGS' PADDING_X

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osimart/create-storefront",
-  "version": "1.0.25",
+  "version": "1.0.27",
   "description": "Osimart storefront platform — logic, platform pages and CLI; extended by every theme repo",
   "type": "module",
   "main": "./nuxt.config.ts",