@eightshift/frontend-libs-tailwind 4.0.0-beta.5 → 4.0.0-beta.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -8,6 +8,15 @@ This projects adheres to [Semantic Versioning](https://semver.org/) and [Keep a
8
8
 
9
9
  ## [4.0.0]
10
10
 
11
+ ### 4.0.0-beta.7
12
+
13
+ - Export `createChunkedComponent` from `/scripts` and `/scripts/helpers`, with deferred loaders, promise compatibility, explicit or inferred exports, and a configurable Suspense fallback (default `null`).
14
+
15
+ ### 4.0.0-beta.6
16
+
17
+ - Add the boolean `removeUnreferencedStyles` option to `defineThemeBuild` so custom CSS callbacks can opt into removing unreferenced entry stylesheet originals after generating hashed replacements. Existing defaults remain unchanged; aliases and detected references retain originals. Custom or disabled publishers cannot use this option.
18
+ - Document the cleanup opt-in and the requirement to pin dynamically constructed stable CSS URLs with aliases; extra styles, lazy CSS, source maps and CSS compilation remain unchanged.
19
+
11
20
  ### 4.0.0-beta.5
12
21
 
13
22
  - Use ESLint 9 to satisfy the React lint plugin peer range without changing lint rules.
package/README.md CHANGED
@@ -12,6 +12,42 @@ This library is meant to bring you the modern front-end development tools to the
12
12
  ## Documentation
13
13
  **For the full documentation please check this [link](https://eightshift.com).**
14
14
 
15
+ ## Lazy React components
16
+
17
+ Import `createChunkedComponent` from `@eightshift/frontend-libs-tailwind/scripts`
18
+ (or `/scripts/helpers`) after installing a published version containing this helper.
19
+ Create the wrapper at module scope, not inside render:
20
+
21
+ ```jsx
22
+ import { createChunkedComponent } from '@eightshift/frontend-libs-tailwind/scripts';
23
+ import { Spinner } from '@eightshift/ui-components/icons';
24
+
25
+ const BlockEditor = createChunkedComponent(
26
+ () => import('./block-editor'),
27
+ 'BlockEditor',
28
+ <Spinner className='m-16 size-32!' />,
29
+ );
30
+ ```
31
+
32
+ The optional third argument is the Suspense fallback; it defaults to `null` (no loading UI).
33
+ Supply your existing spinner to retain project-specific appearance. Props pass through
34
+ unchanged. The lazy component is created once per factory call. Use a loader function
35
+ for deferred loading: it is first called when React renders the component. An existing
36
+ promise is also accepted, but its loading has already started.
37
+
38
+ Specify `'default'` for a default export or the exact name for a named export.
39
+ Without an export name, exactly one function export (excluding `__esModule`) must
40
+ exist; default exports are not preferred over other function exports. Explicitly name
41
+ `memo` and `forwardRef` exports, which are objects and are not inferred. Unresolvable
42
+ exports reject with `Unable to resolve chunked component` (including the requested
43
+ name when provided). Import failures propagate unchanged; handle failures with an
44
+ error boundary, not the Suspense fallback.
45
+
46
+ To replace a local helper after release, change its consumers to the package import
47
+ and pass the existing fallback as the third argument. No icon registry or static/runtime
48
+ icon lookup changes are required. This helper is independent of Bun and does not
49
+ replace `dynamicImport`, which eagerly iterates discovery contexts.
50
+
15
51
  ## Bun build migration
16
52
 
17
53
  The Webpack configuration and `webpack/*` imports have been removed. Projects must replace their Webpack configuration and scripts; this is a breaking change. The Bun helpers are available from `@eightshift/frontend-libs-tailwind/bun/build.mjs`, including `build`, `generateDiscovery`, `generateResponsiveClasses`, and `wordpressPlugin`.
@@ -449,7 +485,14 @@ Structured conventional CSS omits unreferenced stable entry styles only after th
449
485
  same-directory hashed stylesheet and manifest are generated. Alias targets and
450
486
  references in packaged files or generated wrappers retain the stable stylesheet;
451
487
  queries, fragments and escaped names are considered conservatively. Custom `css`
452
- callbacks retain their entry styles. Hooks that construct CSS URLs dynamically
488
+ callbacks retain their entry styles by default. With the default publisher, set
489
+ `defineThemeBuild({ root, css: customCss, removeUnreferencedStyles: true })` to opt
490
+ custom CSS into the same scoped cleanup, or set `removeUnreferencedStyles: false`
491
+ to retain originals with the conventional compiler. The option must be a boolean
492
+ and cannot be supplied with custom or disabled `publish`. It does not change CSS
493
+ compilation, order, hashed stylesheet contents, or `extraCss` handling. Install a
494
+ library version `4.0.0-beta.6` or newer before enabling it; beta.5 ignores it.
495
+ Hooks that construct CSS URLs dynamically
453
496
  must pin the stable path with an alias; static inspection cannot certify computed
454
497
  URLs. Extra styles, script intermediates and source maps are not blanket-removed.
455
498
  Low-level packagers can opt into this scoped behavior with
@@ -26,6 +26,9 @@ import { prepareSharedFonts } from './shared-fonts.mjs';
26
26
  * optimizeImports controls Bun's package barrel optimization for browser builds.
27
27
  * UI Components is optimized by default; pass [] to disable the explicit default.
28
28
  * watch: false disables watching; an object overrides the safe watch defaults.
29
+ * @param {object} [options]
30
+ * @param {boolean} [options.removeUnreferencedStyles] Override entry CSS cleanup
31
+ * for default publication; omitted enables it only with the default CSS compiler.
29
32
  */
30
33
  export function defineThemeBuild(options = {}) {
31
34
  if (Object.hasOwn(options, 'publicationLayout')) {
@@ -50,6 +53,7 @@ export function defineThemeBuild(options = {}) {
50
53
  editor,
51
54
  responsive = {},
52
55
  css,
56
+ removeUnreferencedStyles = css === undefined,
53
57
  discovery,
54
58
  ssr,
55
59
  publish,
@@ -63,6 +67,14 @@ export function defineThemeBuild(options = {}) {
63
67
  throw new TypeError('sharedFonts must be a boolean and requires default theme publication');
64
68
  }
65
69
 
70
+ if (typeof removeUnreferencedStyles !== 'boolean') {
71
+ throw new TypeError('removeUnreferencedStyles must be a boolean');
72
+ }
73
+
74
+ if (Object.hasOwn(options, 'removeUnreferencedStyles') && publish !== undefined) {
75
+ throw new TypeError('removeUnreferencedStyles requires default theme publication');
76
+ }
77
+
66
78
  if (typeof createPlugins !== 'function') {
67
79
  throw new TypeError('createPlugins must be a function');
68
80
  }
@@ -544,7 +556,7 @@ export function defineThemeBuild(options = {}) {
544
556
  retain: additions.retain,
545
557
  previousPublic: resolve(root, 'public'),
546
558
  root: outdir,
547
- removeUnreferencedStyles: css === undefined,
559
+ removeUnreferencedStyles,
548
560
  flatDir,
549
561
  entries,
550
562
  ssrDir,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@eightshift/frontend-libs-tailwind",
3
- "version": "4.0.0-beta.5",
3
+ "version": "4.0.0-beta.7",
4
4
  "description": "A framework for creating modern Gutenberg themes with styling provided by Tailwind CSS.",
5
5
  "author": {
6
6
  "name": "Eightshift team",
@@ -0,0 +1,49 @@
1
+ import { createElement, lazy, Suspense } from 'react';
2
+
3
+ const resolveExportedComponent = (module, exportName) => {
4
+ if (exportName === 'default') {
5
+ return module?.default ?? null;
6
+ }
7
+
8
+ if (exportName) {
9
+ return module?.[exportName] ?? null;
10
+ }
11
+
12
+ const exportedEntries = Object.entries(module ?? {}).filter(([key, value]) => key !== '__esModule' && typeof value === 'function');
13
+
14
+ return exportedEntries.length === 1 ? exportedEntries[0][1] : null;
15
+ };
16
+
17
+ const resolveLazyModule = (moduleLoaderOrPromise, exportName) =>
18
+ Promise.resolve(typeof moduleLoaderOrPromise === 'function' ? moduleLoaderOrPromise() : moduleLoaderOrPromise).then((module) => {
19
+ const Component = resolveExportedComponent(module, exportName);
20
+
21
+ if (!Component) {
22
+ throw new Error(`Unable to resolve chunked component${exportName ? ` "${exportName}"` : ''}.`);
23
+ }
24
+
25
+ return { default: Component };
26
+ });
27
+
28
+ /**
29
+ * Create a stable lazy component. Call outside render; prefer a loader to defer loading.
30
+ *
31
+ * @param {Function|Promise} moduleLoaderOrPromise Module loader or already-started promise.
32
+ * @param {string} [exportName] Explicit export; otherwise infer the only function export.
33
+ * @param {import('react').ReactNode} [fallback=null] Content displayed while loading.
34
+ * @returns {Function} Component forwarding props through a Suspense boundary.
35
+ */
36
+ export const createChunkedComponent = (moduleLoaderOrPromise, exportName, fallback = null) => {
37
+ const LazyComponent = lazy(() => resolveLazyModule(moduleLoaderOrPromise, exportName));
38
+
39
+ const ChunkedComponent = (props) =>
40
+ createElement(
41
+ Suspense,
42
+ {
43
+ fallback,
44
+ },
45
+ createElement(LazyComponent, props),
46
+ );
47
+
48
+ return ChunkedComponent;
49
+ };
@@ -3,3 +3,4 @@
3
3
  export { getBreakpointData, getBreakpointNames, getGlobalManifest, getBreakpointUiData, getResponsiveData } from './breakpoints';
4
4
  export { cookies } from './cookies';
5
5
  export { dynamicImport } from './dynamic-import';
6
+ export { createChunkedComponent } from './chunked-component';
package/scripts/index.js CHANGED
@@ -22,3 +22,4 @@ export { STORE_NAME, BUILD_VERSION, setStore, setStoreGlobalWindow, setConfigFla
22
22
  export { getBreakpointData, getBreakpointNames, getGlobalManifest, getBreakpointUiData, getResponsiveData } from './helpers/breakpoints';
23
23
  export { cookies } from './helpers/cookies';
24
24
  export { dynamicImport } from './helpers/dynamic-import';
25
+ export { createChunkedComponent } from './helpers/chunked-component';