npm package: @sirkitts/hello
Description: Time-aware, locale-savvy greetings with voice flair 🌎🗣️
Author: SirKitts
Latest version: 1.0.5

# 👋 @sirkitts/hello

**Time-aware, locale-savvy, and voice-enabled greetings—because every "hello" deserves personality.**

`hello` is a lightweight utility that returns a friendly greeting based on the time of day, user name, and locale. It even speaks out loud in supported browsers (optional). Great for login screens, personal dashboards, chatbots, and expressive UI touches.

[![npm (scoped)](https://img.shields.io/npm/v/@sirkitts/hello.svg)](https://github.com/sirkitts/hello)

# 👋 hello

[![npm version](https://img.shields.io/npm/v/@sirkitts/hello.svg)](https://www.npmjs.com/package/@sirkitts/hello)
[![install size](https://packagephobia.com/badge?p=@sirkitts/hello)](https://packagephobia.com/result?p=@sirkitts/hello)
[![license](https://img.shields.io/npm/l/@sirkitts/hello.svg)](https://github.com/SirKitts/hello/blob/main/LICENSE)
<!-- [![build status](https://github.com/SirKitts/hello/actions/workflows/release.yml/badge.svg)](https://github.com/SirKitts/hello/actions) -->
---

## ✨ Features

- ⏰ Time-based greetings (morning, afternoon, evening)
- 🌍 Locale-aware defaults (supports `en`, `ja`, `de`—extensible)
- 🔉 Optional voice greeting with `speechSynthesis`
- 🤝 Supports both CommonJS and ES Modules
- 🧩 Works with string or config object input
- 🧪 SSR-safe: auto-detects browser-only APIs

---

### Install ###

```
$ npm install @sirkitts/hello
```

### Usage ###
```
const hello = require("@sirkitts/hello");

hello("World!");
//=> "Hello World!"

Hello World!
```

### Params (optional) ###
```
obj                 -> this can be string - (example. name of a person)
                    -> or an object (example.
                        config = {
                          name: 'Jack',
                          greetings: '',
                          greetingsList: [],
                          exclamation: '!',
                        };)
                    -> default ""
                    -> if no name, it will display a random greet based on greetingsList

greetings           -> string - commonly used greeting words
                    -> default ""

greetingsList       -> list of greetings other than the default greetings
                    -> default greetings ["Hello", "Hi", "Welcome", dayGreet]
                    -> day greet is based on current time (ie Good morning, Good afternoon, Good evening)

exclamation         -> exclamation point added to the end of greetings.
                    -> default ""

dayGreetings:       --> replaced default dayGreet values
                    --> example: ['Guten Morgen', 'Guten Tag', 'Guten Abend']
                    --> will replaced the default (Good morning, Good afternoon, Good evening)

greetListExclude:   --> boolean
                    --> default false - set to true to remove the default greetings ["Hello", "Hi", "Welcome"]

speak:              --> boolean
                    --> default false - set to true to hear voice

```

### Samples ###

Basic string input

```
import hello from 'hello';

console.log( hello('Alice') );
// "Good afternoon! Alice"  (based on current time & locale)

console.log( hello());
console.log( hello("Jack") );
console.log( hello("John", "Welcome aboard!") );
console.log( hello("Jose", "", ["Hey", "Ahoy there", "No way"], "!") );
```

Full config object

```
let config = {
  name: 'Jack', 
  greetings: '', 
  greetingsList: [], 
  exclamation: ',',
  // dayGreetings: ['Guten Morgen', 'Guten Tag', 'Guten Abend'], 
  // greetListExclude: true,
  // speak: true
};
console.log( hello(config) );

hello({
  name: 'Dennis',
  greetingsList: ['Ahoy', 'Hey there'],
  dayGreetings: ['Bonsoir', 'Bon après-midi', 'Bonjour'],
  exclamation: ' 👋',
  speak: true,
});
```

### Sample Results ###
```
Welcome 
Hello Jack
Welcome aboard! John
Hi! Jose
Good evening, Jack
```

### 🌐 Locale Support ###

hello auto-detects the browser’s language:

```
| Language | Code | Sample Greeting     |
|----------|------|---------------------|
| English  | en   | Good morning!       |
| Japanese | ja   | おはようございます！ |
| German   | de   | Guten Abend!        |

```

You can customize greetings per locale using the dayGreetings and greetingsList config options.

### 📦 API  ###
Ts

```
hello(
  input: string | {
    name?: string;
    greetings?: string;
    greetingsList?: string[];
    dayGreetings?: string[];
    exclamation?: string;
    greetListExclude?: boolean;
    speak?: boolean;
  },
  greetingOverride = '',
  greetingsList = [],
  exclamation = '!',
  speak = false
): string
```

Returns a friendly string like "Hello! Jack" or "おはようございます！" and speaks it aloud if enabled.

### 🧠 Why Use It? ###

Sometimes you just want to say “hi” like you mean it. Whether it’s a smart homepage, a chatbot intro, or a morning dashboard—this module adds warmth without effort.

### License ###

---

Feel free to personalize it with badges, emojis, or your preferred tone. Want a minimalistic version too, or a copy-paste publish command for npm?