ionic-team · mapsandapps · Jul 10, 2023 · Jun 9, 2023 · Jun 9, 2023 · Jun 9, 2023
@@ -54,6 +54,7 @@ Ionic's documentation is built using [Docusaurus](https://docusaurus.io/). The c
     - `components/` - styles split out into the components they target
 - `static/`
   - `demos/` - self-contained demos, optionally presented by pages via `demoUrl` YAML frontmatter
+  - `usage/` - playgrounds that can be scaffolded by running `npm run playground:new` [(docs)](_templates/README.md#new-playground-template)
 - `versioned_docs/` - versions of the docs created by the docusaurus versioning command
 - `versioned_sidebars/` - versions of the docs sidebars created by the docusaurus versioning command
 

@@ -0,0 +1,32 @@
+# Hygen templates
+
+The templates in this directory are intended to be used with [hygen](https://www.hygen.io/) to generate boilerplate files. Check out [the root package.json](../package.json) to see if there are any custom commands to use them (e.g. `npm run playground:new`). You can also run e.g. `hygen playground new` to use a generator.
+
+Some helpful docs links for updating/creating templates:
+
+- [enquirer](https://github.com/enquirer/enquirer#toggle-prompt) for building command line prompts
+- [inflection](https://www.hygen.io/docs/templates#helpers-and-inflections) and [change case](https://www.hygen.io/docs/templates#change-case-helpers) for e.g. changing the case of variables submitted via the prompts
+
+# New playground template
+
+## Generation
+
+To create a new playground, run `npm run playground:new`. This will walk you through some prompts to decide what files for the generator to scaffold for the playground, and what their paths should be.
+
+The path defaults to `basic`. If there is already a basic playground, you'll want to input a different path for the playground.
+
+The CSS option will add extra files if you need to include custom CSS in your playground. This is often not needed.
+
+If you need a component for multiple versions of Ionic Framework, you (currently) need to run the generator once for each version.
+
+## Usage
+
+Once you've generated your playground, you need to add it to the main markdown file in the docs (e.g. [docs/api/button.md](../docs/api/button.md)) by doing something similar to the following example:
+
+```
+## Feature
+
+import Feature from '@site/static/usage/v7/button/feature/index.md';
+
+<Feature />
+```
@@ -0,0 +1,7 @@
+---
+# this file's location depends on whether or not the css option is selected via the prompt
+to: "<%= `static/usage/v${version}/${name.replace('ion-', '')}/${path}/${css ? 'angular/example_component_html.md' : 'angular.md'}` %>"
+---
+```html
+<<%= name %>></<%= name %>>
+```
@@ -0,0 +1,9 @@
+---
+# this file only gets generated if `css` (from the command line prompt) is true
+to: "<%= css ? `static/usage/v${version}/${name.replace('ion-', '')}/${path}/angular/example_component_css.md` : null %>"
+---
+```css
+<%= name %> {
+  /* styles go here */
+}
+```
@@ -0,0 +1,32 @@
+---
+arbitrary: <% nameWithoutIon = name.replace('ion-', ''); numberOfAncestors = (path.match(/\//g) || []).length; directoryChanges = '../'.repeat(numberOfAncestors) %>
+to: "<%= `static/usage/v${version}/${nameWithoutIon}/${path}/demo.html` %>"
+---
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title><%= h.changeCase.titleCase(nameWithoutIon) %></title>
+    <link rel="stylesheet" href="<%= directoryChanges %>../../../common.css" />
+    <script src="<%= directoryChanges %>../../../common.js"></script>
+    <script type="module" src="https://cdn.jsdelivr.net/npm/@ionic/core@<%= version %>/dist/ionic/ionic.esm.js"></script>
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ionic/core@<%= version %>/css/ionic.bundle.css" /><% if (css){ %>
+
+    <style>
+      <%= name %> {
+        /* styles go here */
+      }
+    </style><% } %>
+  </head>
+
+  <body>
+    <ion-app>
+      <ion-content>
+        <div class="container">
+          <<%= name %>></<%= name %>>
+        </div>
+      </ion-content>
+    </ion-app>
+  </body>
+</html>
@@ -0,0 +1,13 @@
+---
+arbitrary: <% nameWithoutIon = name.replace('ion-', '') %>
+# this template is only used if `css` (from the command line prompt) is false
+to: "<%= css ? null : `static/usage/v${version}/${nameWithoutIon}/${path}/index.md` %>"
+---
+import Playground from '@site/src/components/global/Playground';
+
+import javascript from './javascript.md';
+import react from './react.md';
+import vue from './vue.md';
+import angular from './angular.md';
+
+<Playground version="<%= version %>" code={{ javascript, react, vue, angular }} src="<%= `usage/v${version}/${nameWithoutIon}/${path}/demo.html` %>" />
@@ -0,0 +1,37 @@
+---
+arbitrary: <% nameWithoutIon = name.replace('ion-', '') %>
+# this template is only used if `css` (from the command line prompt) is true
+to: "<%= css ? `static/usage/v${version}/${nameWithoutIon}/${path}/index.md` : null %>"
+---
+import Playground from '@site/src/components/global/Playground';
+
+import javascript from './javascript.md';
+
+import react_main_tsx from './react/main_tsx.md';
+import react_main_css from './react/main_css.md';
+
+import vue from './vue.md';
+
+import angular_example_component_html from './angular/example_component_html.md';
+import angular_example_component_css from './angular/example_component_css.md';
+
+<Playground
+  version="<%= version %>"
+  code={{
+    javascript,
+    react: {
+      files: {
+        'src/main.tsx': react_main_tsx,
+        'src/main.css': react_main_css,
+      },
+    },
+    vue,
+    angular: {
+      files: {
+        'src/app/example.component.html': angular_example_component_html,
+        'src/app/example.component.css': angular_example_component_css,
+      },
+    },
+  }}
+  src="<%= `usage/v${version}/${nameWithoutIon}/${path}/demo.html` %>"
+/>
@@ -0,0 +1,12 @@
+---
+to: "<%= `static/usage/v${version}/${name.replace('ion-', '')}/${path}/javascript.md` %>"
+---
+```html
+<<%= name %>></<%= name %>><% if (css){ %>
+
+<style>
+  <%= name %> {
+    /* styles go here */
+  }
+</style><% } %>
+```
diff --git a/_templates/playground/new/prompt.js b/_templates/playground/new/prompt.js
@@ -0,0 +1,32 @@
+// see types of prompts:
+// https://github.com/enquirer/enquirer/tree/master/examples
+//
+module.exports = [
+  {
+    type: 'input',
+    name: 'name',
+    message: 'Which component is this playground for?',
+    initial: 'ion-button',
+  },
+  {
+    type: 'input',
+    name: 'path',
+    message: 'What should the playground path be?',
+    hint: 'e.g. `theming/colors`',
+    initial: 'basic',
+  },
+  {
+    type: 'select',
+    name: 'version',
+    message: 'Select the Ionic Framework version for the playground',
+    initial: '7',
+    choices: ['6', '7'],
+  },
+  {
+    type: 'toggle',
+    name: 'css',
+    message: 'Do you want CSS scaffolded?',
+    enabled: 'Yes',
+    disabled: 'No',
+  },
+];
@@ -0,0 +1,17 @@
+---
+arbitrary: <% pascalName = h.changeCase.pascal(name) %>
+# this file's location depends on whether or not the css option is selected via the prompt
+to: "<%= `static/usage/v${version}/${name.replace('ion-', '')}/${path}/${css ? 'react/main_tsx.md' : 'react.md'}` %>"
+---
+```tsx
+import React from 'react';
+import { <%= pascalName %> } from '@ionic/react';
+
+function Example() {
+  return (
+    <<%= pascalName %>></<%= pascalName %>>
+  );
+}
+export default Example;
+```
+
@@ -0,0 +1,9 @@
+---
+# this file only gets generated if `css` (from the command line prompt) is true
+to: "<%= css ? `static/usage/v${version}/${name.replace('ion-', '')}/${path}/react/main_css.md` : null %>"
+---
+```css
+<%= name %> {
+  /* styles go here */
+}
+```
@@ -0,0 +1,27 @@
+---
+arbitrary: <% pascalName = h.changeCase.pascal(name) %>
+to: "<%= `static/usage/v${version}/${name.replace('ion-', '')}/${path}/vue.md` %>"
+---
+```html
+<template>
+  <<%= name %>>
+  </<%= name %>>
+</template>
+
+<script lang="ts">
+  import { <%= pascalName %> } from '@ionic/vue';
+  import { defineComponent } from 'vue';
+
+  export default defineComponent({
+    components: {
+      <%= pascalName %>,
+    },
+  });
+</script><% if (css){ %>
+
+<style scoped>
+  <%= name %> {
+    /* styles go here */
+  }
+</style><% } %>
+```