Merge branch 'next' into chore/more-states-za

.editorconfig

@@ -9,5 +9,4 @@ trim_trailing_whitespace = true
 insert_final_newline = true
 
 [*.md]
-max_line_length = off
 trim_trailing_whitespace = false

docs/api/ApiIndex.vue

@@ -96,7 +96,9 @@ onUnmounted(() => window.removeEventListener('keydown', apiSearchFocusHandler));
       <h2 :id="slugify(section.text)">{{ section.text }}</h2>
       <div class="api-groups">
         <div v-for="item of section.items" :key="item.text" class="api-group">
-          <h3>{{ item.text }}</h3>
+          <h3>
+            <a :href="item.link + '.html'">{{ item.text }}</a>
+          </h3>
           <ul>
             <li v-for="h of item.headers" :key="h.anchor">
               <a :href="item.link + '.html#' + slugify(h.anchor)">{{
@@ -158,19 +160,19 @@ h3 {
   margin-bottom: 64px;
 }
 
-.api-groups a {
+.api-groups ul a {
   font-size: 15px;
   font-weight: 500;
   line-height: 2;
   color: var(--vp-c-text-code);
   transition: color 0.5s;
 }
 
-.dark .api-groups a {
+.dark .api-groups ul a {
   font-weight: 400;
 }
 
-.api-groups a:hover {
+.api-groups ul a:hover {
   color: var(--vp-c-green);
   transition: none;
 }
@@ -233,7 +235,7 @@ h3 {
     padding-top: 32px;
   }
 
-  .api-groups a {
+  .api-groups ul a {
     font-size: 14px;
   }
 

docs/guide/localization.md

@@ -44,7 +44,7 @@ If our built-in faker instances don't satisfy your needs, you can build your own
 
 ```ts
 import type { LocaleDefinition } from '@faker-js/faker';
-import { Faker, de_CH, de, en } from '@faker-js/faker';
+import { Faker, de_CH, de, en, base } from '@faker-js/faker';
 
 const customLocale: LocaleDefinition = {
   title: 'My custom locale',
@@ -54,10 +54,18 @@ const customLocale: LocaleDefinition = {
 };
 
 export const customFaker = new Faker({
-  locale: [customLocale, de_CH, de, en, global],
+  locale: [customLocale, de_CH, de, en, base],
 });
 ```
 
+In this example there are 5 locales. Each of these is checked in order, and the first locale which contains the requested data will be used:
+
+- `customLocale` is your custom locale definition which will override all other fallback definitions.
+- `de_CH` is a specific locale definition that overrides some German definitions with `CH` (Switzerland) data.
+- `de` is a generic `de` (German) locale definition.
+- `en` is a generic `en` (English) locale definition. This is our most complete locale, so we add it to fill some gaps. Depending on your needs, you might want or not want to have it as a fallback.
+- `base` is the base locale definition which contains definitions that can be used in every language (e.g. emojis).
+
 ## Available locales
 
 <!-- LOCALES-AUTO-GENERATED-START -->
@@ -69,6 +77,7 @@ export const customFaker = new Faker({
 | `af_ZA`       | Afrikaans                 | `fakerAF_ZA`       |
 | `ar`          | Arabic                    | `fakerAR`          |
 | `az`          | Azerbaijani               | `fakerAZ`          |
+| `base`        | Base                      | `fakerBASE`        |
 | `cz`          | Czech                     | `fakerCZ`          |
 | `de`          | German                    | `fakerDE`          |
 | `de_AT`       | German (Austria)          | `fakerDE_AT`       |

docs/guide/upgrading.md

@@ -60,12 +60,12 @@ const b = customFaker.internet.emoji();
 **New**
 
 ```ts
-import { Faker, de_CH, de, en, global } from '@faker-js/faker';
+import { Faker, de_CH, de, en, base } from '@faker-js/faker';
 
 // same as fakerDE_CH
 export const customFaker = new Faker({
   // Now multiple fallbacks are supported
-  locale: [de_CH, de, en, global],
+  locale: [de_CH, de, en, base],
 });
 const a = customFaker.internet.email();
 const b = customFaker.internet.emoji();

package.json

@@ -112,7 +112,7 @@
     "glob": "~9.3.2",
     "npm-run-all": "~4.1.5",
     "picocolors": "~1.0.0",
-    "prettier": "2.8.4",
+    "prettier": "2.8.7",
     "prettier-plugin-organize-imports": "~3.2.2",
     "react": "~18.2.0",
     "react-dom": "~18.2.0",

scripts/apidoc/moduleMethods.ts

@@ -1,7 +1,7 @@
 import type { DeclarationReflection, ProjectReflection } from 'typedoc';
 import type { Method } from '../../docs/.vitepress/components/api-docs/method';
 import { writeApiDocsData, writeApiDocsModulePage } from './apiDocsWriter';
-import { analyzeSignature, toBlock } from './signature';
+import { analyzeSignature, stripAbsoluteFakerUrls, toBlock } from './signature';
 import {
   extractModuleFieldName,
   extractModuleName,
@@ -40,7 +40,7 @@ function processModuleMethod(module: DeclarationReflection): PageAndDiffIndex {
   const moduleName = extractModuleName(module);
   const moduleFieldName = extractModuleFieldName(module);
   console.log(`Processing Module ${moduleName}`);
-  const comment = toBlock(module.comment);
+  const comment = stripAbsoluteFakerUrls(toBlock(module.comment));
 
   const methods: Method[] = [];
 

scripts/apidoc/signature.ts

@@ -40,8 +40,14 @@ function prettifyMethodName(method: string): string {
   );
 }
 
+export const MISSING_DESCRIPTION = 'Missing';
+
 export function toBlock(comment?: Comment): string {
-  return joinTagParts(comment?.summary) || 'Missing';
+  return joinTagParts(comment?.summary) || MISSING_DESCRIPTION;
+}
+
+export function stripAbsoluteFakerUrls(markdown: string): string {
+  return markdown.replace(/https:\/\/(next.)?fakerjs.dev\//g, '/');
 }
 
 let markdown: MarkdownRenderer;
@@ -304,7 +310,17 @@ function typeToText(type_?: Type, short = false): string {
 
     case 'reference':
       if (!type.typeArguments || !type.typeArguments.length) {
-        return type.name;
+        const reflection = type.reflection as DeclarationReflection | undefined;
+        const reflectionType = reflection?.type;
+        if (
+          (reflectionType?.type === 'literal' ||
+            reflectionType?.type === 'union') &&
+          !type.name.match(/Char$/)
+        ) {
+          return typeToText(reflectionType, short);
+        } else {
+          return type.name;
+        }
       } else if (type.name === 'LiteralUnion') {
         return [
           typeToText(type.typeArguments[0], short),

scripts/generateLocales.ts

@@ -125,10 +125,15 @@ function generateLocaleFile(locale: string): void {
     }
   }
 
-  if (locales[locales.length - 1] !== 'en') {
+  // TODO christopher 2023-03-07: Remove 'en' fallback in a separate PR
+  if (locales[locales.length - 1] !== 'en' && locale !== 'base') {
     locales.push('en');
   }
 
+  if (locales[locales.length - 1] !== 'base') {
+    locales.push('base');
+  }
+
   let content = `
       ${autoGeneratedCommentHeader}
 
@@ -148,8 +153,10 @@ function generateLocaleFile(locale: string): void {
   writeFileSync(resolve(pathLocale, `${locale}.ts`), content);
 }
 
-function tryLoadLocalesMainIndexFile(pathModules: string): LocaleDefinition {
-  let localeDef: LocaleDefinition;
+function tryLoadLocalesMainIndexFile(
+  pathModules: string
+): LocaleDefinition | undefined {
+  let localeDef: LocaleDefinition | undefined;
   // This call might fail, if the module setup is broken.
   // Unfortunately, we try to fix it with this script
   // Thats why have a fallback logic here, we only need the title anyway
@@ -165,9 +172,10 @@ function tryLoadLocalesMainIndexFile(pathModules: string): LocaleDefinition {
         resolve(pathModules, 'index.ts'),
         'utf-8'
       );
-      localeDef = {
-        title: localeIndex.match(/title: '(.*)',/)[1],
-      };
+      const title = localeIndex.match(/title: '(.*)',/)?.[1];
+      if (title) {
+        localeDef = { title };
+      }
     } catch {
       console.error(`Failed to load ${pathModules} or manually parse it.`, e);
     }

src/definitions/location.ts

@@ -45,17 +45,17 @@ export type LocationDefinitions = LocaleEntry<{
   country_code: Array<{ alpha2: string; alpha3: string }>;
 
   /**
-   * The names of this country's states.
+   * The names of this country's states, or other first-level administrative areas.
    */
   state: string[];
 
   /**
-   * The abbreviated names of this country's states.
+   * The abbreviated names of this country's states, or other first-level administrative areas.
    */
   state_abbr: string[];
 
   /**
-   * The names of counties inside the country or state.
+   * The names of counties, or other second-level administrative areas, inside the country's states.
    */
   county: string[];
 

src/locale/af_ZA.ts

@@ -5,8 +5,9 @@
 
 import { Faker } from '../faker';
 import af_ZA from '../locales/af_ZA';
+import base from '../locales/base';
 import en from '../locales/en';
 
 export const faker = new Faker({
-  locale: [af_ZA, en],
+  locale: [af_ZA, en, base],
 });

src/locale/ar.ts

@@ -5,8 +5,9 @@
 
 import { Faker } from '../faker';
 import ar from '../locales/ar';
+import base from '../locales/base';
 import en from '../locales/en';
 
 export const faker = new Faker({
-  locale: [ar, en],
+  locale: [ar, en, base],
 });

src/locale/az.ts

@@ -5,8 +5,9 @@
 
 import { Faker } from '../faker';
 import az from '../locales/az';
+import base from '../locales/base';
 import en from '../locales/en';
 
 export const faker = new Faker({
-  locale: [az, en],
+  locale: [az, en, base],
 });

src/locale/base.ts

@@ -0,0 +1,11 @@
+/*
+ * This file is automatically generated.
+ * Run 'pnpm run generate:locales' to update.
+ */
+
+import { Faker } from '../faker';
+import base from '../locales/base';
+
+export const faker = new Faker({
+  locale: base,
+});

src/locale/cz.ts

@@ -4,9 +4,10 @@
  */
 
 import { Faker } from '../faker';
+import base from '../locales/base';
 import cz from '../locales/cz';
 import en from '../locales/en';
 
 export const faker = new Faker({
-  locale: [cz, en],
+  locale: [cz, en, base],
 });

src/locale/de.ts

@@ -4,9 +4,10 @@
  */
 
 import { Faker } from '../faker';
+import base from '../locales/base';
 import de from '../locales/de';
 import en from '../locales/en';
 
 export const faker = new Faker({
-  locale: [de, en],
+  locale: [de, en, base],
 });

src/locale/de_AT.ts

@@ -4,10 +4,11 @@
  */
 
 import { Faker } from '../faker';
+import base from '../locales/base';
 import de from '../locales/de';
 import de_AT from '../locales/de_AT';
 import en from '../locales/en';
 
 export const faker = new Faker({
-  locale: [de_AT, de, en],
+  locale: [de_AT, de, en, base],
 });

src/locale/de_CH.ts

@@ -4,10 +4,11 @@
  */
 
 import { Faker } from '../faker';
+import base from '../locales/base';
 import de from '../locales/de';
 import de_CH from '../locales/de_CH';
 import en from '../locales/en';
 
 export const faker = new Faker({
-  locale: [de_CH, de, en],
+  locale: [de_CH, de, en, base],
 });