chore(jp): merge recent update

.github/workflows/CI.yml

@@ -0,0 +1,33 @@
+# GitHub Actions docs
+# https://help.github.com/en/articles/about-github-actions
+# https://help.github.com/en/articles/workflow-syntax-for-github-actions
+
+name: Install Dependencies, Lint
+
+on: [pull_request]
+
+jobs:
+  test:
+    name: Test on node ${{ matrix.node_version }} and ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        node_version: [16]
+        os: [windows-latest, macOS-latest]
+
+    steps:
+    - uses: actions/checkout@v1
+    - name: Use Node.js ${{ matrix.node_version }}
+      uses: actions/setup-node@v1
+      with:
+        node-version: ${{ matrix.node_version }}
+    - name: Install Dependencies
+      run: npm ci --legacy-peer-deps
+    - name: Lint
+      run: npm run lint
+    # Lint changes should be pushed
+    # to the branch before the branch
+    # is merge eligible.
+    - name: Check Diff
+      run: git diff --exit-code
+      shell: bash

.prettierignore

@@ -1,13 +1,15 @@
 src/theme/DocItem
 src/theme/DocPage
 legacy-stencil-components
-node_modules
 scripts/bak
-src/styles.bak
-src/pages
+
 docs/api
 docs/native
 docs/cli/commands
 
+static/code/stackblitz
+
 .docusaurus
-.github
+.github
+build
+node_modules

CONTRIBUTING.md

@@ -54,8 +54,9 @@ 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 created 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_sitebars/` - versions of the docs sidebars created by the docusaurus versioning command
+- `versioned_sidebars/` - versions of the docs sidebars created by the docusaurus versioning command
 
 ## Authoring Content
 
@@ -84,7 +85,7 @@ The Ionic docs have been translated into Japanese and are in the process of bein
 
 We use Crowdin for our translation service. You can participate in the translation effort on the [Ionic Crowdin page](https://crowdin.com/project/ionic-docs).
 
-_Please submit translation issues to the Crowdin page and not the Ionic Docs GitHub repo_
+_Please submit translation issues to the Crowdin page and not the Ionic Docs GitHub repo._
 
 The Japanese translation of the docs were built by an independent team, lead by [rdlabo](https://github.com/rdlabo) and can be found and contributed to on the [ionic-jp group's `ionic-docs` project page](https://github.com/ionic-jp/ionic-docs).
 

_templates/README.md

@@ -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 create 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.
+
+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 />
+```

_templates/playground/new/angular.md.ejs.t

@@ -0,0 +1,7 @@
+---
+# this file's location depends on whether or not the css option or angular_ts option is selected via the prompt
+to: "<%= `static/usage/v${version}/${name.replace('ion-', '')}/${path}/${(css || angular_ts) ? 'angular/example_component_html.md' : 'angular.md'}` %>"
+---
+```html
+<<%= name %>></<%= name %>>
+```

_templates/playground/new/angular_example_component_css.md.ejs.t

@@ -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 */
+}
+```

_templates/playground/new/angular_example_component_ts.md.ejs.t

@@ -0,0 +1,17 @@
+---
+# this file only gets generated if `angular_ts` (from the command line prompt) is true
+to: "<%= angular_ts ? `static/usage/v${version}/${name.replace('ion-', '')}/${path}/angular/example_component_ts.md` : null %>"
+---
+```ts
+import { Component } from '@angular/core';
+
+@Component({
+  selector: 'app-example',
+  templateUrl: 'example.component.html',
+<% if (css){ -%>
+  styleUrls: ['./example.component.css'],
+<% } -%>
+})
+export class ExampleComponent {
+}
+```

_templates/playground/new/demo.html.ejs.t

@@ -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>

_templates/playground/new/index.js

@@ -0,0 +1,64 @@
+const changeCase = require('change-case');
+
+// see types of prompts:
+// https://github.com/enquirer/enquirer/tree/master/examples
+//
+module.exports = {
+  prompt: ({ inquirer }) => {
+    const questions = [
+      {
+        type: 'input',
+        name: 'name',
+        message: 'Which component is this playground for?',
+        initial: 'ion-button',
+        validate(value) {
+          return value.match(/^ion-[a-z/-]*[a-z]+$/) ? true : "Component name must be kebab-case and begin with 'ion-'";
+        },
+      },
+      {
+        type: 'input',
+        name: 'path',
+        message: 'What should the playground path be?',
+        hint: 'e.g. `basic` or `theming/colors`',
+        validate(value) {
+          return value.match(/^[a-z]+[a-z/-]*[a-z]+$/)
+            ? true
+            : "Path should begin and end with a letter and only contain lowercase letters, '-', or '/'";
+        },
+      },
+      {
+        type: 'select',
+        name: 'version',
+        message: 'Select the Ionic Framework version for the playground',
+        initial: '7',
+        choices: ['6', '7'],
+      },
+      {
+        type: 'toggle',
+        name: 'css',
+        message: 'Generate custom CSS files?',
+        enabled: 'Yes',
+        disabled: 'No',
+      },
+      {
+        type: 'toggle',
+        name: 'angular_ts',
+        message: 'Generate an Angular TypeScript file?',
+        enabled: 'Yes',
+        disabled: 'No',
+      },
+    ];
+
+    return inquirer.prompt(questions).then((answers) => {
+      const componentName = changeCase.pascal(answers.path.split('/').pop());
+      console.log(
+        `\nTo use this component in a docs markdown file, include\nthe following:\n\n## ${componentName}\n\nimport ${componentName} from '@site/static/usage/v7/${answers.name.replace(
+          'ion-',
+          ''
+        )}/${answers.path}/index.md';\n\n<${componentName} />\n`
+      );
+
+      return answers;
+    });
+  },
+};

_templates/playground/new/index.md.ejs.t

@@ -0,0 +1,60 @@
+---
+arbitrary: <% nameWithoutIon = name.replace('ion-', '') %>
+to: "<%= `static/usage/v${version}/${nameWithoutIon}/${path}/index.md` %>"
+---
+import Playground from '@site/src/components/global/Playground';
+
+import javascript from './javascript.md';
+<% if (css){ %>
+import react_main_tsx from './react/main_tsx.md';
+import react_main_css from './react/main_css.md';
+
+<% } else { -%>
+import react from './react.md';
+<% } -%>
+import vue from './vue.md';
+<% if (css || angular_ts){ %>
+import angular_example_component_html from './angular/example_component_html.md';
+<% } else { -%>
+import angular from './angular.md';
+<% } -%>
+<% if (angular_ts){ -%>
+import angular_example_component_ts from './angular/example_component_ts.md';
+<% } -%>
+<% if (css){ -%>
+import angular_example_component_css from './angular/example_component_css.md';
+<% } -%>
+
+<Playground
+  version="<%= version %>"
+  code={{
+    javascript,
+<% if (css){ -%>
+    react: {
+      files: {
+        'src/main.tsx': react_main_tsx,
+        'src/main.css': react_main_css,
+      },
+    },
+<% } else { -%>
+    react,
+<% } -%>
+    vue,
+<% if (angular_ts || css){ -%>
+    angular: {
+      files: {
+        'src/app/example.component.html': angular_example_component_html,
+<% if (angular_ts){ -%>
+        'src/app/example.component.ts': angular_example_component_ts,
+<% } -%>
+<% if (css){ -%>
+        'src/app/example.component.css': angular_example_component_css,
+<% } -%>
+      },
+    },
+<% } else { -%>
+    angular,
+<% } -%>
+  }}
+  src="usage/v<%= version %>/<%= nameWithoutIon %>/<%= path %>/demo.html"
+/>

_templates/playground/new/javascript.md.ejs.t

@@ -0,0 +1,14 @@
+---
+to: "<%= `static/usage/v${version}/${name.replace('ion-', '')}/${path}/javascript.md` %>"
+---
+```html
+<<%= name %>></<%= name %>>
+<% if (css){ -%>
+
+<style>
+  <%= name %> {
+    /* styles go here */
+  }
+</style>
+<% } -%>
+```

_templates/playground/new/react.md.ejs.t

@@ -0,0 +1,19 @@
+---
+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';<% if (css){ %>
+
+import './main.css';<% } %>
+
+function Example() {
+  return (
+    <<%= pascalName %>></<%= pascalName %>>
+  );
+}
+export default Example;
+```
+

_templates/playground/new/react_main_css.md.ejs.t

@@ -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 */
+}
+```

_templates/playground/new/vue.md.ejs.t

@@ -0,0 +1,28 @@
+---
+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>
+<% } -%>
+```

crowdin.yml

@@ -8,6 +8,5 @@ files:
   - source: /docs/**/*
     translation: /i18n/%two_letters_code%/docusaurus-plugin-content-docs/current/**/%original_file_name%
     ignore:
-      - /docs/api/**/*
       - /docs/cli/commands/**/*
       - /docs/native/**/*