@emulsify/core 4.0.2 → 4.0.3

package/.storybook/utils.js

@@ -5,6 +5,7 @@
 import {
   attachStorybookBehaviors,
   genericStorybookAdapter,
+  noneStorybookAdapter,
   normalizeStorybookPlatformAdapter,
 } from '../src/storybook/platform-behaviors.js';
 import { setupTwig } from '../src/storybook/twig/setup.js';
@@ -93,6 +94,7 @@ export {
   attachStorybookBehaviors,
   fetchCSSFiles,
   genericStorybookAdapter,
+  noneStorybookAdapter,
   normalizeStorybookPlatformAdapter,
   setupTwig,
 };

package/README.md

@@ -34,7 +34,7 @@ See [Version Evolution](docs/version-evolution.md) for more release history.
 
 Twig and React are equally valid ways to build component libraries with Emulsify Core. The right authoring model depends on the consuming project:
 
-- Use Twig for CMS themes and server-rendered template systems. Drupal has a dedicated adapter today; Craft CMS and WordPress + Timber can use the generic adapter unless a project adds platform-specific behavior.
+- Use Twig for CMS themes and server-rendered template systems. Drupal has a dedicated adapter today; Craft CMS and WordPress + Timber can use the `none` adapter unless a project adds platform-specific behavior.
 - Use React for standalone UI libraries, application components, or projects that already use React.
 - Use mixed Twig and React when a design system needs to document both CMS-rendered and JavaScript-rendered components in the same Storybook instance.
 
@@ -53,7 +53,7 @@ Every project should provide a `project.emulsify.json` file at the project root:
 ```json
 {
   "project": {
-    "platform": "generic",
+    "platform": "none",
     "name": "example",
     "machineName": "example"
   }
@@ -77,7 +77,7 @@ The documentation is split by task:
 | [Component Authoring](docs/component-authoring.md)        | Choosing Twig, React, or mixed Storybook authoring and comparing component examples.                                  |
 | [Storybook](docs/storybook.md)                            | Rendering Twig stories, using `renderTwig()`, understanding Twig runtime helpers, and mixing Twig with React stories. |
 | [Project Structure And Output](docs/project-structure.md) | Configuring `src/components`, root `./components`, `variant.structureImplementations`, and expected output paths.     |
-| [Platform Adapters](docs/platform-adapters.md)            | Understanding `generic`, `drupal`, platform resolution order, and Drupal SDC behavior.                                |
+| [Platform Adapters](docs/platform-adapters.md)            | Understanding `none`, `drupal`, platform resolution order, and Drupal SDC behavior.                                   |
 | [Extension Points](docs/extension-points.md)              | Adding Vite plugins, Tailwind CSS, Storybook preview overrides, and other framework tooling.                          |
 | [Performance](docs/performance.md)                        | Understanding sourcemaps, eager Twig imports, Tailwind scanning, copied files, and fixture validation.                |
 | [Native Twig Extensions](docs/native-twig-extensions.md)  | Using `bem()`, `add_attributes()`, and `switch/case/default/endswitch` in Twig.js.                                    |
@@ -86,24 +86,24 @@ The documentation is split by task:
 
 ## Known Limitations
 
-- Implemented platform adapters are currently `generic` and `drupal`. WordPress + Timber and Craft CMS are supported as Twig-oriented use cases through the generic adapter today; dedicated adapters are future opportunities. See [Platform Adapters](docs/platform-adapters.md).
+- Implemented platform adapters are currently `none` and `drupal`. WordPress + Timber and Craft CMS are supported as Twig-oriented use cases through the `none` adapter today. Dedicated adapters are future opportunities. See [Platform Adapters](docs/platform-adapters.md).
 - Storybook's Twig resolver eagerly imports Twig modules and raw Twig source. This is reliable for `include()` and `source()`, but large Twig libraries should keep Storybook source roots intentional. See [Performance](docs/performance.md).
 - Production sourcemaps are enabled by default unless a project overrides Vite config through `config/emulsify-core/vite/plugins.*`. See [Performance](docs/performance.md).
 - Project extensions use the public `config/emulsify-core` directory: `config/emulsify-core/vite/plugins.*` for Vite, `config/emulsify-core/storybook/...` for Storybook, and `config/emulsify-core/a11y.config.js` for a11y. See [Extension Points](docs/extension-points.md).
 - Webpack-specific customizations must be migrated manually to Vite plugins or `extendConfig()`. See [Migration](docs/migration-4x.md).
-- Drupal SDC mirroring only applies when the Drupal adapter and SDC settings are enabled. Generic projects should expect output to remain in `dist/`. See [Platform Adapters](docs/platform-adapters.md).
+- Drupal SDC mirroring only applies when the Drupal adapter and SDC settings are enabled. `none` projects should expect output to remain in `dist/`. See [Platform Adapters](docs/platform-adapters.md).
 
 ## Supported Project Shapes
 
 Release-readiness coverage validates:
 
 - Drupal SDC projects using `src/components`.
-- Generic Twig projects using `src/components`.
+- `none` platform Twig projects using `src/components`.
 - Root `./components` projects.
 - Projects using multiple `variant.structureImplementations`.
 - Mixed Twig + React Storybook projects.
 
-WordPress + Timber and Craft CMS are Twig-based project use cases that can use the `generic` adapter today. Dedicated adapters for those platforms are future opportunities. The implemented adapters in this package are currently `generic` and `drupal`.
+WordPress + Timber and Craft CMS are Twig-based project use cases that can use the `none` adapter today. Dedicated adapters for those platforms are future opportunities. The implemented adapters in this package are currently `none` and `drupal`.
 
 ## Public Imports
 

package/config/vite/environment.js

@@ -5,7 +5,7 @@
  * entries, plugins, and the Vite config.
  *
  * Highlights:
- *  - `platform`: from env var or project.emulsify.json (default "generic").
+ *  - `platform`: from env var or project.emulsify.json (default "none").
  *  - `SDC`: boolean from project.emulsify.json `project.singleDirectoryComponents`.
  *  - `structureOverrides`: true when safe `variant.structureImplementations` exist.
  *  - `structureRoots`: array of directories from `variant.structureImplementations`.
@@ -21,7 +21,7 @@ import { resolveProjectConfig } from './project-config.js';
  *   projectDir: string,
  *   srcDir: string,
  *   srcExists: boolean,
- *   platform: 'drupal' | 'generic' | string,
+ *   platform: 'drupal' | 'none' | string,
  *   SDC: boolean,
  *   structureOverrides: boolean,
  *   structureRoots: string[],

package/config/vite/platforms.js

@@ -5,8 +5,8 @@
  * decisions can be used by Node-side Vite config and Storybook browser code.
  */
 
-const genericAdapter = {
-  name: 'generic',
+const noneAdapter = {
+  name: 'none',
   outputStrategy: 'dist',
   storybook: {
     loadDrupalBehaviorShim: false,
@@ -36,7 +36,8 @@ const drupalAdapter = {
 };
 
 const adapters = {
-  generic: genericAdapter,
+  none: noneAdapter,
+  generic: noneAdapter,
   drupal: drupalAdapter,
 };
 
@@ -50,21 +51,39 @@ function cloneAdapter(adapter) {
   return JSON.parse(JSON.stringify(adapter));
 }
 
+/**
+ * Normalize configured platform names to canonical identifiers.
+ *
+ * `generic` is retained as a legacy alias for existing projects, but new
+ * configuration should use `none` for projects without platform-specific
+ * behavior.
+ *
+ * @param {*} platform - Candidate platform name.
+ * @returns {string} Canonical platform name.
+ */
+export function normalizePlatformName(platform = 'none') {
+  const key = (platform || '').toString().toLowerCase().trim();
+  if (!key || key === 'generic') {
+    return 'none';
+  }
+  return key;
+}
+
 /**
  * Resolve the platform adapter for a normalized platform name.
  *
- * Unknown platforms intentionally use generic behavior while preserving the
+ * Unknown platforms intentionally use `none` behavior while preserving the
  * resolved `platform` string separately on the environment object.
  *
- * @param {string} [platform='generic'] - Normalized platform name.
+ * @param {string} [platform='none'] - Normalized platform name.
  * @returns {object} Serializable platform adapter.
  */
-export function getPlatformAdapter(platform = 'generic') {
-  const key = (platform || 'generic').toString().toLowerCase().trim();
+export function getPlatformAdapter(platform = 'none') {
+  const key = normalizePlatformName(platform);
   if (key === 'drupal') {
     return cloneAdapter(drupalAdapter);
   }
-  return cloneAdapter(genericAdapter);
+  return cloneAdapter(noneAdapter);
 }
 
 export { adapters };

package/config/vite/project-config.js

@@ -8,7 +8,7 @@
  */
 
 import { normalize, resolve, sep } from 'path';
-import { getPlatformAdapter } from './platforms.js';
+import { getPlatformAdapter, normalizePlatformName } from './platforms.js';
 import { resolveProjectStructure } from './project-structure.js';
 import { safeExists, safeReadJson } from './utils/fs-safe.js';
 
@@ -53,8 +53,12 @@ function normalizeIdentifier(value) {
  * @returns {string} Stable cache-key segment.
  */
 function projectConfigEnvSignature(env = {}) {
+  const platformOverride = normalizeIdentifier(env.EMULSIFY_PLATFORM);
+
   return JSON.stringify({
-    EMULSIFY_PLATFORM: normalizeIdentifier(env.EMULSIFY_PLATFORM),
+    EMULSIFY_PLATFORM: platformOverride
+      ? normalizePlatformName(platformOverride)
+      : '',
   });
 }
 
@@ -119,11 +123,12 @@ export function resolveProjectConfig(
   const srcExists = safeExists(srcCandidate);
   const srcDir = srcExists ? srcCandidate : resolve(root, 'components');
 
-  const platform =
+  const resolvedPlatform =
     normalizeIdentifier(env.EMULSIFY_PLATFORM) ||
     normalizeIdentifier(rawConfig?.project?.platform) ||
     normalizeIdentifier(rawConfig?.variant?.platform) ||
-    'generic';
+    'none';
+  const platform = normalizePlatformName(resolvedPlatform);
   const platformAdapter = getPlatformAdapter(platform);
 
   const singleDirectoryComponents = Boolean(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emulsify/core",
-  "version": "4.0.2",
+  "version": "4.0.3",
   "description": "Bundled tooling for Storybook development + Vite Build",
   "keywords": [
     "component library",

package/scripts/audit.js

@@ -329,7 +329,7 @@ function resolveAuditEnvironment(projectDir) {
     return {
       env: {
         projectDir,
-        platform: 'generic',
+        platform: 'none',
         namespaceRoots: {},
         projectStructure: {},
       },

package/src/storybook/platform-behaviors.js

@@ -2,7 +2,7 @@
  * @file Platform-specific Storybook behavior helpers.
  */
 
-export const genericStorybookAdapter = {
+export const noneStorybookAdapter = {
   loadDrupalBehaviorShim: false,
   attachDrupalBehaviors: false,
   registerDrupalTwigFilters: false,
@@ -10,15 +10,17 @@ export const genericStorybookAdapter = {
   allowSyncXhrSource: false,
 };
 
+export const genericStorybookAdapter = noneStorybookAdapter;
+
 /**
  * Normalize optional platform adapter flags into the full Storybook shape.
  *
  * @param {object} [adapter] - Candidate Storybook adapter flags.
- * @returns {object} Storybook adapter flags with generic defaults.
+ * @returns {object} Storybook adapter flags with non-platform defaults.
  */
 export function normalizeStorybookPlatformAdapter(adapter = {}) {
   return {
-    ...genericStorybookAdapter,
+    ...noneStorybookAdapter,
     ...(adapter || {}),
   };
 }
@@ -27,7 +29,7 @@ export function normalizeStorybookPlatformAdapter(adapter = {}) {
  * Attach platform-specific behaviors after a Storybook render.
  *
  * Drupal behavior attachment is opt-in through the active platform adapter.
- * Generic and unknown platforms return without creating Drupal globals.
+ * `none` and unknown platforms return without creating Drupal globals.
  *
  * @param {object} [options={}] - Attachment options.
  * @param {object} [options.adapter] - Active Storybook platform adapter.