@pikacss/core 0.0.39 → 0.0.40

package/README.md

@@ -10,39 +10,28 @@ pnpm add @pikacss/core
 
 ## Quick Start
 
-**pika.config.ts**:
-```typescript
-import { defineEngineConfig } from '@pikacss/core'
-
-export default defineEngineConfig({
-  // Your configuration
-})
-```
-
-**Your code**:
 ```typescript
 import { createEngine, defineEngineConfig } from '@pikacss/core'
 
 const config = defineEngineConfig({
-  // Engine configuration
-  prefix: 'pk-',
-  defaultSelector: '.%',
-  plugins: []
+	// Engine configuration
+	prefix: 'pk-',
+	defaultSelector: '.%',
+	plugins: []
 })
 
-const engine = createEngine(config)
-await engine.setup()
+// createEngine is async and returns a fully initialized engine
+const engine = await createEngine(config)
 ```
 
 ## Features
 
 - ⚡ High-performance Atomic CSS-in-JS engine
 - 🎯 Type-safe with full TypeScript support
-- 🔌 Extensible plugin system
-- 🎨 Built-in support for shortcuts, selectors, variables, keyframes
-- 📦 Works at build-time, zero runtime overhead
-- 🔧 Fully configurable
-- 🌐 Framework-agnostic core
+- 🔌 Extensible plugin system with hooks
+- 🎨 Built-in support for shortcuts, selectors, variables, keyframes, and important rules
+- 🔧 Fully configurable with type-safe helpers
+- 🌐 Framework-agnostic core (zero dependencies except csstype)
 
 ## Usage for Integration Developers
 
@@ -52,37 +41,52 @@ await engine.setup()
 import { createEngine, defineEngineConfig } from '@pikacss/core'
 
 const config = defineEngineConfig({
-  // Prefix for generated atomic CSS class names
-  prefix: 'pk-',
-  
-  // Default selector format (% will be replaced with atomic ID)
-  defaultSelector: '.%',
-  
-  // Plugins to extend functionality
-  plugins: [],
-  
-  // Global CSS preflights
-  preflights: [],
+	// Prefix for generated atomic CSS class names
+	prefix: 'pk-',
+
+	// Default selector format (% will be replaced with atomic ID)
+	defaultSelector: '.%',
+
+	// Plugins to extend functionality
+	plugins: [],
+
+	// Global CSS preflights
+	preflights: [],
 })
 
-const engine = createEngine(config)
-await engine.setup()
+// createEngine is async - it returns a fully initialized engine
+const engine = await createEngine(config)
 ```
 
-### Engine Methods
+### Engine Methods and Properties
 
-The engine provides methods for managing CSS generation:
+The `Engine` instance provides methods and sub-systems for managing CSS generation:
 
 ```typescript
-// Add global CSS
+// Add global CSS preflight
 engine.addPreflight('* { box-sizing: border-box; }')
 
-// Access sub-systems
-engine.variables  // CSS variables management
-engine.keyframes  // CSS keyframes management
-engine.selectors  // CSS selectors management
-engine.shortcuts  // CSS shortcuts management
-engine.important  // Important rules management
+// Process style items and get atomic class IDs
+const classNames = await engine.use({ color: 'red' }, { display: 'flex' })
+
+// Render generated preflights
+const preflightCSS = await engine.renderPreflights(true)
+
+// Render generated atomic styles
+const atomicCSS = await engine.renderAtomicStyles(true)
+
+// Access sub-systems (provided by built-in plugins)
+engine.variables // { store: Map, add: (variables) => void }
+engine.keyframes // { store: Map, add: (...keyframes) => void }
+engine.selectors // { resolver: SelectorResolver, add: (...selectors) => void }
+engine.shortcuts // { resolver: ShortcutResolver, add: (...shortcuts) => void }
+
+// Access configuration
+engine.config // ResolvedEngineConfig
+
+// Autocomplete helpers
+engine.appendAutocompleteSelectors('hover', 'focus')
+engine.appendAutocompleteStyleItemStrings('flex-center')
 ```
 
 ### Configuration
@@ -93,32 +97,32 @@ Use `defineEngineConfig` for type-safe configuration:
 import { defineEngineConfig } from '@pikacss/core'
 
 export default defineEngineConfig({
-  // Prefix for atomic class IDs
-  prefix: 'pk-',
-  
-  // Default selector format (% = atomic ID)
-  defaultSelector: '.%',
-  
-  // Global CSS preflights
-  preflights: [
-    ':root { --primary: #3b82f6; }',
-    // Or function:
-    ({ engine, isFormatted }) => '/* Generated CSS */'
-  ],
-  
-  // Shortcuts configuration
-  shortcuts: {
-    shortcuts: [
-      ['flex-center', {
-        display: 'flex',
-        alignItems: 'center',
-        justifyContent: 'center'
-      }],
-    ]
-  },
-  
-  // Plugins to extend functionality
-  plugins: []
+	// Prefix for atomic class IDs
+	prefix: 'pk-',
+
+	// Default selector format (% = atomic ID)
+	defaultSelector: '.%',
+
+	// Global CSS preflights (string or function)
+	preflights: [
+		':root { --primary: #3b82f6; }',
+		// Or function:
+		(engine, isFormatted) => '/* Generated CSS */'
+	],
+
+	// Shortcuts configuration
+	shortcuts: {
+		shortcuts: [
+			['flex-center', {
+				display: 'flex',
+				alignItems: 'center',
+				justifyContent: 'center'
+			}],
+		]
+	},
+
+	// Plugins to extend functionality
+	plugins: []
 })
 ```
 
@@ -127,8 +131,8 @@ export default defineEngineConfig({
 ### Main Exports
 
 ```typescript
-// Engine creation
-export function createEngine(config: EngineConfig): Engine
+// Engine creation (async)
+export function createEngine(config?: EngineConfig): Promise<Engine>
 
 // Type-safe config helpers
 export function defineEngineConfig(config: EngineConfig): EngineConfig
@@ -141,54 +145,87 @@ export function defineShortcut(shortcut: Shortcut): Shortcut
 export function defineVariables(variables: VariablesDefinition): VariablesDefinition
 
 // Utilities
-export { log, createLogger } from './internal/utils'
+export {
+	appendAutocompleteCssPropertyValues,
+	appendAutocompleteExtraCssProperties,
+	appendAutocompleteExtraProperties,
+	appendAutocompletePropertyValues,
+	appendAutocompleteSelectors,
+	appendAutocompleteStyleItemStrings,
+	createLogger,
+	log,
+	renderCSSStyleBlocks,
+}
 ```
 
 ### Engine Instance
 
-The `Engine` instance provides methods for managing the CSS generation:
+The `Engine` instance provides:
+
+**Core methods:**
+- `engine.addPreflight(css)` - Add global CSS preflight
+- `engine.use(...styleItems)` - Process style items and return atomic class IDs
+- `engine.renderPreflights(isFormatted)` - Render all preflight CSS
+- `engine.renderAtomicStyles(isFormatted, options?)` - Render atomic style CSS
+
+**Sub-systems (provided by built-in plugins):**
+- `engine.variables` - CSS variables management with `store` and `add()`
+- `engine.keyframes` - CSS keyframes management with `store` and `add()`
+- `engine.selectors` - CSS selectors management with `resolver` and `add()`
+- `engine.shortcuts` - CSS shortcuts management with `resolver` and `add()`
 
-- `engine.setup()` - Initialize the engine with plugins
-- `engine.addPreflight(css)` - Add global CSS
-- `engine.variables` - Manage CSS variables
-- `engine.keyframes` - Manage CSS keyframes
-- `engine.selectors` - Manage CSS selectors
-- `engine.shortcuts` - Manage CSS shortcuts
-- `engine.important` - Manage important rules
+**Properties:**
+- `engine.config` - Resolved engine configuration
+- `engine.store` - Internal storage for atomic styles and IDs
+- `engine.extract` - Style extraction function
 
 ## Plugin Development
 
-Create custom plugins to extend PikaCSS:
+Create custom plugins to extend PikaCSS using the `EnginePlugin` interface:
 
 ```typescript
-import type { Plugin } from '@pikacss/core'
-
-export function myPlugin(): Plugin {
-  return {
-    name: 'my-plugin',
-    
-    setup(api) {
-      // Add preflights
-      api.addPreflight({
-        css: '/* your global CSS */'
-      })
-      
-      // Add rules
-      api.addRule({
-        /* rule configuration */
-      })
-      
-      // Add shortcuts
-      api.addShortcut({
-        /* shortcut configuration */
-      })
-      
-      // Add variants
-      api.addVariant({
-        /* variant configuration */
-      })
-    }
-  }
+/* eslint-disable pikacss/pika-module-augmentation */
+import type { EnginePlugin } from '@pikacss/core'
+import { defineEnginePlugin } from '@pikacss/core'
+
+export function myPlugin(): EnginePlugin {
+	return defineEnginePlugin({
+		name: 'my-plugin',
+
+		// Optional: Control execution order ('pre' | 'post')
+		order: 'pre',
+
+		// Hook into engine lifecycle
+		async configureEngine(engine) {
+			// Add global CSS
+			engine.addPreflight('/* plugin styles */')
+
+			// Add custom shortcuts
+			engine.shortcuts.add([
+				'my-shortcut',
+				{ display: 'flex', gap: '1rem' }
+			])
+
+			// Add custom selectors
+			engine.selectors.add(['hover', '$:hover'])
+		},
+
+		// Transform style definitions
+		async transformStyleDefinitions(definitions) {
+			// Modify or add style definitions
+			return definitions
+		},
+
+		// Other available hooks:
+		// - configureRawConfig(config)
+		// - rawConfigConfigured(config)
+		// - configureResolvedConfig(config)
+		// - transformSelectors(selectors)
+		// - transformStyleItems(styleItems)
+		// - preflightUpdated()
+		// - atomicStyleAdded(atomicStyle)
+		// - autocompleteConfigUpdated()
+	})
 }
 ```
 

package/dist/index.cjs

@@ -223,7 +223,7 @@ const hooks = {
 	transformStyleItems: (plugins, styleItems) => execAsyncHook(plugins, "transformStyleItems", styleItems),
 	transformStyleDefinitions: (plugins, styleDefinitions) => execAsyncHook(plugins, "transformStyleDefinitions", styleDefinitions),
 	preflightUpdated: (plugins) => execSyncHook(plugins, "preflightUpdated", void 0),
-	atomicStyleAdded: (plugins) => execSyncHook(plugins, "atomicStyleAdded", void 0),
+	atomicStyleAdded: (plugins, atomicStyle) => execSyncHook(plugins, "atomicStyleAdded", atomicStyle),
 	autocompleteConfigUpdated: (plugins) => execSyncHook(plugins, "autocompleteConfigUpdated", void 0)
 };
 const orderMap = new Map([

package/dist/index.d.cts

@@ -326,20 +326,18 @@ declare class Engine {
 }
 //#endregion
 //#region src/internal/plugin.d.ts
-type DefineHooks<Hooks extends Record<string, [type: 'sync' | 'async', payload: any, returnValue?: any]>> = Hooks;
-type EngineHooksDefinition = DefineHooks<{
-  configureRawConfig: ['async', config: EngineConfig$1];
-  rawConfigConfigured: ['sync', config: EngineConfig$1, void];
-  configureResolvedConfig: ['async', resolvedConfig: ResolvedEngineConfig];
-  configureEngine: ['async', engine: Engine];
-  transformSelectors: ['async', selectors: string[]];
-  transformStyleItems: ['async', styleItems: ResolvedStyleItem[]];
-  transformStyleDefinitions: ['async', styleDefinitions: ResolvedStyleDefinition[]];
-  preflightUpdated: ['sync', void];
-  atomicStyleAdded: ['sync', AtomicStyle];
-  autocompleteConfigUpdated: ['sync', void];
-}>;
-type EnginePluginHooksOptions = { [K in keyof EngineHooksDefinition]?: EngineHooksDefinition[K][0] extends 'async' ? (...params: EngineHooksDefinition[K][1] extends void ? [] : [payload: EngineHooksDefinition[K][1]]) => Awaitable<EngineHooksDefinition[K][1] | void> : (...params: EngineHooksDefinition[K][1] extends void ? [] : [payload: EngineHooksDefinition[K][1]]) => EngineHooksDefinition[K][1] | void };
+interface EnginePluginHooksOptions {
+  configureRawConfig?: (config: EngineConfig$1) => Awaitable<EngineConfig$1 | void>;
+  rawConfigConfigured?: (config: EngineConfig$1) => void;
+  configureResolvedConfig?: (resolvedConfig: ResolvedEngineConfig) => Awaitable<ResolvedEngineConfig | void>;
+  configureEngine?: (engine: Engine) => Awaitable<void>;
+  transformSelectors?: (selectors: string[]) => Awaitable<string[] | void>;
+  transformStyleItems?: (styleItems: ResolvedStyleItem[]) => Awaitable<ResolvedStyleItem[] | void>;
+  transformStyleDefinitions?: (styleDefinitions: ResolvedStyleDefinition[]) => Awaitable<ResolvedStyleDefinition[] | void>;
+  preflightUpdated?: () => void;
+  atomicStyleAdded?: (atomicStyle: AtomicStyle) => void;
+  autocompleteConfigUpdated?: () => void;
+}
 interface EnginePlugin extends EnginePluginHooksOptions {
   name: string;
   order?: 'pre' | 'post';

package/dist/index.d.mts

@@ -326,20 +326,18 @@ declare class Engine {
 }
 //#endregion
 //#region src/internal/plugin.d.ts
-type DefineHooks<Hooks extends Record<string, [type: 'sync' | 'async', payload: any, returnValue?: any]>> = Hooks;
-type EngineHooksDefinition = DefineHooks<{
-  configureRawConfig: ['async', config: EngineConfig$1];
-  rawConfigConfigured: ['sync', config: EngineConfig$1, void];
-  configureResolvedConfig: ['async', resolvedConfig: ResolvedEngineConfig];
-  configureEngine: ['async', engine: Engine];
-  transformSelectors: ['async', selectors: string[]];
-  transformStyleItems: ['async', styleItems: ResolvedStyleItem[]];
-  transformStyleDefinitions: ['async', styleDefinitions: ResolvedStyleDefinition[]];
-  preflightUpdated: ['sync', void];
-  atomicStyleAdded: ['sync', AtomicStyle];
-  autocompleteConfigUpdated: ['sync', void];
-}>;
-type EnginePluginHooksOptions = { [K in keyof EngineHooksDefinition]?: EngineHooksDefinition[K][0] extends 'async' ? (...params: EngineHooksDefinition[K][1] extends void ? [] : [payload: EngineHooksDefinition[K][1]]) => Awaitable<EngineHooksDefinition[K][1] | void> : (...params: EngineHooksDefinition[K][1] extends void ? [] : [payload: EngineHooksDefinition[K][1]]) => EngineHooksDefinition[K][1] | void };
+interface EnginePluginHooksOptions {
+  configureRawConfig?: (config: EngineConfig$1) => Awaitable<EngineConfig$1 | void>;
+  rawConfigConfigured?: (config: EngineConfig$1) => void;
+  configureResolvedConfig?: (resolvedConfig: ResolvedEngineConfig) => Awaitable<ResolvedEngineConfig | void>;
+  configureEngine?: (engine: Engine) => Awaitable<void>;
+  transformSelectors?: (selectors: string[]) => Awaitable<string[] | void>;
+  transformStyleItems?: (styleItems: ResolvedStyleItem[]) => Awaitable<ResolvedStyleItem[] | void>;
+  transformStyleDefinitions?: (styleDefinitions: ResolvedStyleDefinition[]) => Awaitable<ResolvedStyleDefinition[] | void>;
+  preflightUpdated?: () => void;
+  atomicStyleAdded?: (atomicStyle: AtomicStyle) => void;
+  autocompleteConfigUpdated?: () => void;
+}
 interface EnginePlugin extends EnginePluginHooksOptions {
   name: string;
   order?: 'pre' | 'post';

package/dist/index.mjs

@@ -222,7 +222,7 @@ const hooks = {
 	transformStyleItems: (plugins, styleItems) => execAsyncHook(plugins, "transformStyleItems", styleItems),
 	transformStyleDefinitions: (plugins, styleDefinitions) => execAsyncHook(plugins, "transformStyleDefinitions", styleDefinitions),
 	preflightUpdated: (plugins) => execSyncHook(plugins, "preflightUpdated", void 0),
-	atomicStyleAdded: (plugins) => execSyncHook(plugins, "atomicStyleAdded", void 0),
+	atomicStyleAdded: (plugins, atomicStyle) => execSyncHook(plugins, "atomicStyleAdded", atomicStyle),
 	autocompleteConfigUpdated: (plugins) => execSyncHook(plugins, "autocompleteConfigUpdated", void 0)
 };
 const orderMap = new Map([

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@pikacss/core",
   "type": "module",
-  "version": "0.0.39",
+  "version": "0.0.40",
   "author": "DevilTea <ch19980814@gmail.com>",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/pikacss/pikacss.git",
+    "url": "https://github.com/pikacss/pikacss.github.io.git",
     "directory": "packages/core"
   },
   "bugs": {
-    "url": "https://github.com/pikacss/pikacss/issues"
+    "url": "https://github.com/pikacss/pikacss.github.io/issues"
   },
   "keywords": [
     "pikacss",