Merge pull request #28 from samk-dev/release/1.1.0

release: 1.1.0

.prettierignore

@@ -17,7 +17,7 @@ node_modules
 **/**/.output
 
 # Content
-docs/content/*.md
+docs/content/**/.md
 
 # Testing
 reports

README.md

@@ -6,25 +6,31 @@
 [![Nuxt][nuxt-src]][nuxt-href]
 [![UIkit][uikit-src]][uikit-href]
 
-UIkit 3 Nuxt module
-
 UIkit is a lightweight and modular front-end framework for developing fast and powerful web interfaces
 
 Nuxt compatibility: `^3.0.0` Bridge: `false`
 
-- [📖  Documentation](https://nuxt-uikit3-docs.vercel.app)
-- [✨  Release Notes](/nuxt-uikit3/CHANGELOG.md)
-- [🏀 Online playground](https://stackblitz.com/edit/nuxt-uikit3-example?file=app.vue)
-- [📖 UIkit 3 Docs](https://getuikit.com/docs/introduction)
-- [📖 Nuxt Docs](https://nuxt.com/docs/getting-started/introduction)
+[![nuxt-uikit-screenshot.jpg](https://i.postimg.cc/hvgjzgHP/nuxt-uikit-screenshot.jpg)](https://postimg.cc/N9JYZhsW)
+
+[📖  Documentation](https://nuxt-uikit.astratto.dev)
+
+[📖 UIkit Docs](https://getuikit.com/docs/introduction)
+
+[📖 Nuxt Docs](https://nuxt.com/docs/getting-started/introduction)
+
+[✨  Release Notes](/nuxt-uikit3/CHANGELOG.md)
+
+[🏀 Online playground](https://stackblitz.com/edit/nuxt-uikit3-example?file=app.vue)
 
 ## Features
 
-- Injects UIkit 3 into Nuxt ✅
-- scss/less to customize UIkit 3 theme ✅
-- Use all UIKit 3 JS components without writing any JS ✅
-- Use UIKit 3 icons pack ✅
-- UIkit 3 documentation in Nuxt Devtools ✅
+- Zero cofig, just plug && play
+- Customize UIkit default theme with scss/less
+- Share scss/less variables && mixins everywhere
+- Use all UIKit JS components without writing any JS
+- Access UIkit JS components api with `useUIkit3` composable
+- Use UIKit default icons pack
+- UIkit documentation in Nuxt Devtools
 
 ## Quick Setup
 
@@ -51,28 +57,17 @@ export default defineNuxtConfig({
 
 That's it! You can now use Nuxt Uikit 3 in your Nuxt app ✨
 
-For additional configuration please refer to [module docs](https://nuxt-uikit3-docs.vercel.app)
+For additional configuration please refer to module [docs](https://nuxt-uikit.astratto.dev)
 
 ## Development
 
 ```bash
-# Install dependencies
-npm install
-
-# Generate type stubs
-npm run dev:prepare -w nuxt-uikit3
-
-# Develop with the playground
-npm run dev -w nuxt-uikit3
-
-# Build the playground
-npm run dev:build -w nuxt-uikit3
-
-# Run ESLint
-npm run lint
-
-# Release new version
-npm run release -w nuxt-uikit3
+# stub
+pnpm uikit:dev:prep
+# dev
+pnpm uikit:dev
+# docs dev
+pnpm docs:dev
 ```
 
 <!-- Badges -->

docs/content/0.index.md

@@ -19,19 +19,20 @@ secondary:
 ---
 
 #title
-Nuxt UIkit 3
+Nuxt UIkit
 
 #description
-This module helps you set up UIkit Framework in your Nuxt application in seconds
+This module helps you set up [UIkit](https://getuikit.com) Framework in your Nuxt application in seconds
 
 #extra
-  ::list
+  ::list{type="success"}
   - Zero cofig, just plug && play
-  - Scss/Less to customize UIkit 3 theme
-  - Share your Scss/Less variables && mixins across your nuxt app
-  - Use all UIKit 3 JS components without writing any JS
-  - Use UIKit 3 default icons pack
-  - UIkit 3 documentation in Nuxt Devtools
+  - Customize UIkit default theme with scss/less
+  - Share scss/less variables && mixins everywhere
+  - Use all UIKit JS components without writing any JS
+  - Access UIkit JS components api with `useUIkit3` composable
+  - Use UIKit default icons pack
+  - UIkit documentation in Nuxt Devtools
   ::
 
 #support

docs/content/1.getting-started/2.module-options.md

@@ -17,7 +17,7 @@ export default defineNuxtConfig({
     css: {
       coreCss: boolean, // default true
       coreTheme: boolean, // default true
-      build: {
+      build: { // default undefined
         preprocessor: 'scss' | 'less',
         stylesPath: string,
         variablesPath: string,

docs/content/2.usage/1.css.md

@@ -2,9 +2,7 @@
 
 After installing `nuxt-uikit3` you can use it in any page or component without any configuration
 
-## Styling pages and components
-
-```html [page/component]
+```html [page/component.vue]
 <template>
   <section class="uk-section uk-section-default">
     <div class="uk-container">
@@ -17,67 +15,53 @@ After installing `nuxt-uikit3` you can use it in any page or component without a
 </template>
 ```
 
-## Available CSS Options
-
-- `coreCss?: boolean` `default: true`
-
-  Enable/Disable the module from loading UIkit 3 core css
-
-- `coreTheme?: boolean` `default: true`
-
-  Enable/Disable the module from loading UIkit 3 default theme css
-
-- `build?: object` `default: undefined`
-
-Build options:
-
-- `preprocessor: 'scss' | 'less'`
+## CSS Options
 
-  Sets what css preprocessor to use
+By default the module loads UIkit core && theme stylesheets.
 
-- `stylesPath: string`
+| Option      | Type    | Default   | Description |
+|-------------|---------|-----------|-------------|
+|`coreCss?`   | boolean | true      | Enable/Disable the module from loading UIkit core css
+|`coreTheme?` | boolean | true      | Enable/Disable the module from loading UIkit default theme css
+|`build?`     | object  | undefined | scss/less build build options
 
-  Path to your site.scss/less ex: `~/assets/scss/site.scss`
+### Scss/Less options
 
-- `variablesPath: string`
-
-  This option allows you to share the variables.scss/less with all pages/components
-
-- `mixinsPath: string`
-
-  This option allows you to share the mixins.scss/less with all pages/components
+::alert{type="info"}
+You need to install your css preprocessor dependencies. ex: `pnpm i -D sass sass-loader` Also check [Scss custom build in the examples](/examples/scss-custom-build).
+::
 
-## Customizing CSS
+| Option        | Type            | Default   | Description |
+|---------------|-----------------|-----------|-------------|
+|`preprocessor` | 'scss' or 'less'| undefined | What css preprocessor to use
+|`stylesPath`   | string          | undefined | Path to your site.scss/less ex: `~/assets/scss/site.scss`
+|`variablesPath`| string          | undefined | Path to variables.scss/less to make it available in all pages/components
+|`mixinsPath`   | string          | undefined | Path to mixins.scss/less to make it available in all pages/components
 
-You can customize UIkit default theme with sass or less. Please checkout [UIkit 3 docs](https://getuikit.com/docs/sass) on how to customize UIkit 3 theme.
+::alert{type="warning"}
+`variablesPath` and `mixinsPath`  are used only to share them in your app. You should also include them in your global styles to be compiled and take effect. Please check UIkit [scss](https://getuikit.com/docs/sass) or [less](https://getuikit.com/docs/less) docs.
+::
 
-Here's an example on how to customize it using sass
+Example of global scss from UIkit docs:
 
-### Sass example
+```scss [~/assets/styles/stie.scss]
 
-1. Install dev dependencies
+// 1. Your custom variables and variable overwrites.
+@import "variables/accordion.scss";
+@import "variables/alert.scss";
+@import "variables/align.scss";
+// … import all
 
-```bash [terminal]
-npm i -D sass sass-loader
-```
+// 2. Import default variables and available mixins.
+@import "uikit/src/scss/variables.scss";
+@import "uikit/src/scss/mixins.scss";
 
-2. Set build option in nuxt.config
+// 3. Your custom mixin overwrites.
+@import "mixins/accordion-mixins.scss";
+@import "mixins/alert-mixins.scss";
+@import "mixins/align-mixins.scss";
+// … import all
 
-```ts [nuxt.config.ts]
-uikit3: {
-    css: {
-      coreCss: false, // disable uikit 3 css
-      coreTheme: false, // disable uikit 3 theme css
-      build: {
-        preprocessor: 'scss',
-        stylesPath: '~/assets/scss/app.scss',
-        variablesPath: '~/assets/scss/variables.scss',
-        mixinsPath: '~/assets/scss/mixins.scss'
-      }
-    },
-    // ...rest of options
+// 4. Import UIkit
+@import "uikit/src/scss/uikit.scss";
 ```
-
-::alert{type="success"}
-That's it ✅ Now you can use your own scss and reference variables from variables.scss file in any component/page
-::

docs/content/2.usage/2.javascript.md

@@ -13,40 +13,71 @@ uikit3: {
 }
 ```
 
-## Usage Example
+## Using data attributes 
 
-Using `data-uk-<component-name>`:
+Using `data-uk-<component-name>` or just `uk-<component-name>`:
 
 ```html
+<script setup lang="ts">
+  const items = [
+    { 
+      title: 'Item', 
+      content: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.' 
+    },
+    { 
+      title: 'Item', 
+      content: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.' 
+    },
+    { 
+      title: 'Item', 
+      content: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.' 
+    }
+  ]
+</script>
+
 <template>
   <ul data-uk-accordion>
-    <li class="uk-open">
-      <a class="uk-accordion-title" href="#">Item 1</a>
-      <div class="uk-accordion-content">
-        <p>
-          Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-          eiusmod tempor incididunt ut labore et dolore magna aliqua.
-        </p>
-      </div>
-    </li>
-    <li>
-      <a class="uk-accordion-title" href="#">Item 2</a>
-      <div class="uk-accordion-content">
-        <p>
-          Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-          eiusmod tempor incididunt ut labore et dolore magna aliqua.
-        </p>
-      </div>
-    </li>
-    <li>
-      <a class="uk-accordion-title" href="#">Item 3</a>
+    <li v-for="(item, i) in items" :key="i">
+      <a class="uk-accordion-title" href="#">
+        {{ item.title }} {{ i }}
+      </a>
       <div class="uk-accordion-content">
         <p>
-          Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-          eiusmod tempor incididunt ut labore et dolore magna aliqua.
+          {{ item.content }}
         </p>
       </div>
     </li>
   </ul>
 </template>
 ```
+
+## Using useUIkit3 Composable
+
+The module provides a composable to access UIkit javascript api programatically. see UIkit [docs](https://getuikit.com/docs/javascript#programmatic-use)
+
+```html [file.vue]
+<script setup lang="ts">
+  const uikit = useUIkit3()
+  
+  function handleShowModal() {
+    uikit?.modal.confirm('UIkit confirm!')
+    .then(
+      function () {
+        console.log('Confirmed.')
+      },
+      function () {
+        console.log('Rejected.')
+      }
+    )
+</script>
+
+<template>
+  <button 
+    type="button" 
+    class="uk-button" 
+    @click="handleShowModal"
+  >
+    Show modal
+  </button>
+</template>
+```

docs/content/2.usage/3.icons.md

@@ -1,10 +1,11 @@
 # Icons
 
-Enable `icons` in module options
+Enable `icons` in module options. Requires UIkit javascript to be enabled, please check UIkit [docs](https://getuikit.com/docs/icon)
 
 ```ts [nuxt.config.ts]
 uikit3: {
   // ...css options
+  js: true,
   icons: true
 }
 ```